Back to Docs

How to Use Per-Session API Keys

Override your account-level API key for specific sessions.

When to Use This

  • • Different providers: Use OpenAI for one session, Anthropic for another
  • • Cost management: Separate keys for personal vs work projects
  • • Team collaboration: Share a session with a team key
  • • Testing: Try new models without affecting account default

How It Works

filepath supports a 3-tier key resolution:

  1. Session key (if set) Highest priority
  2. User account key (your default)
  3. Global env key (for e2e tests only)

If you set a per-session key, all agents in that session use it instead of your account key.

Setting a Session Key

During Session Creation

  1. Click New Session
  2. Fill in name and repo (optional)
  3. Expand Advanced Options
  4. Paste your API key
  5. Click Create

After Session Creation

  1. Open the session
  2. Click Session Settings (gear icon)
  3. Go to Provider API Key tab
  4. Toggle "Use different key for this session"
  5. Paste the new key
  6. Click Save

The change applies immediately to:

  • Existing agents (next message they receive)
  • New agents spawned in this session

Removing a Session Key

  1. Go to Session Settings / Provider API Key
  2. Click Remove Session Key
  3. Confirm

Agents will revert to using your account-level key.

Encryption & Security

Session keys are:

  • Encrypted with AES-GCM (same as account keys)
  • Never logged or exposed in UI
  • Only decrypted when spawning containers
  • Isolated to that session only

Even filepath admins cannot see your keys.

Use Cases

Different Models

Session A: OpenAI GPT-4 for analysis tasks
Session B: Claude for creative writing

Team Projects

- Personal account key: your individual work
- Session key: shared team key for group project

Client Work

- Account key: internal projects
- Session A key: Client A's OpenAI key
- Session B key: Client B's Anthropic key

Monitoring Usage

filepath tracks usage per-session:

  1. Go to Session Settings
  2. View Usage Stats
  3. See: tokens used, API calls, estimated cost

Troubleshooting

"Invalid API key" error

Check the key is valid with the provider directly

"No API key configured for this session"

Either add a session key or ensure account key is set

Session key not being used

Changes apply to NEW messages. Existing in-flight agents may still use old key.

Best Practices

  • • Use account key by default — Simpler, applies everywhere
  • • Session keys for exceptions — Different providers, team sharing
  • • Rotate regularly — Both account and session keys
  • • Monitor costs — Track which sessions are expensive
  • • Delete unused keys — Remove session keys when session is deleted