Using your own API keys (BYOK)

Coffeescribe works out of the box — the platform provides API keys for every provider it uses. But you can optionally bring your own keys (BYOK) so that your requests to a specific provider draw from your provider account instead of the platform's shared quota.

What BYOK does

When you save a working key for a provider, two things happen:

1. Your requests to that provider use your key. Cost goes to your provider account, not the platform's shared quota.
2. The platform token gate is skipped. Coffeescribe does not check or deduct your platform token balance for that generation — because the cost already went to your own provider account. With a working OpenRouter key saved, generating scribes, Quick Reads, and Research does not spend platform tokens.

You only need platform tokens as a backup: if your key fails mid-generation, Coffeescribe falls back to the platform key to finish your work — that fallback does deduct platform tokens.

What happens if my key fails mid-generation?

If your key fails mid-generation (the provider rejects it with an authentication error, a quota error, or any other failure after retries are exhausted), Coffeescribe handles it transparently:

• If you have platform tokens: Coffeescribe falls back to the platform key and finishes your generation automatically. When the generation completes, a toast notification appears: "Your [Provider] key isn't working, so we used your tokens — fix it in Settings." You are taken to Settings → API Keys to review the key.
• If you have no platform tokens: Generation stops and you see a message offering two actions: top up your token balance, or fix or change your key in Settings → API Keys.

The fallback is automatic — Coffeescribe never asks permission or pauses generation mid-way through. Your work completes first; the notification comes after.

What counts as a key failure for OpenRouter? An authentication error (401), an insufficient-credits error (402), a key-limit-exceeded error (403), or a rate-limit error (429) — and any other error after retries. If you set a per-key spend cap in OpenRouter's dashboard and that cap is hit, the cap-exceeded error also triggers the fallback.

Scope: automatic fallback applies to LLM generation routes (scribes, Quick Reads, Research AI). For non-LLM routes (audiobook narration, Apify scraping), a key failure surfaces as an error without an automatic fallback — this is tracked as a follow-up (C2b-tail).

Supported providers

You do not need to add keys for every provider. Leave any provider blank to continue using the platform key for that provider.

Where to manage your keys

Settings → API Keys (full management)

Go to Settings (/settings) and open the API Keys section. All six providers are listed. For each provider you can:

1. Paste your key into the password field.
2. Click Test connection — a live request validates the key against the provider before saving it.
3. Click Save — the key is encrypted and stored. It is never shown again; you will see •••• last4 (the last four characters of your key) as a confirmation.
4. Click Remove to delete a saved key and revert to the platform key.

Testing a key you already saved

Once a key is configured, the test button changes to Test saved key. Click it without pasting anything into the field — Coffeescribe tests the stored key server-side without requiring you to re-enter or re-expose it. This is the quickest way to check whether a configured key is still valid after receiving a fallback notification.

Per-surface "Manage API keys" button

A Manage API keys button also appears directly on the feature surfaces that use BYOK:

Click the button to open a scoped modal showing only the providers relevant to that feature. The modal works the same as the Settings section (Test → Save → Remove).

Security and privacy

• Your key is encrypted with AES-256-GCM before it reaches the database and is never sent back to your browser in plaintext after saving.
• Only the last four characters (•••• last4) are ever displayed.
• The key input uses type="password" — it is masked as you type.
• Keys are stored in the user_api_keys table with row-level security: only your account can read or modify your own keys.
• We never log or transmit your plaintext key beyond the single validation call at save time.
• Test saved key tests the stored encrypted key server-side — the plaintext key is decrypted in memory on the server and used for one validation call only. It is not returned to the browser.

Testing a key before saving

The Test connection button makes a live request to the provider's API using the key you pasted but does not save it. If the test succeeds (green toast), clicking Save will encrypt and store the key. If the test fails (red toast showing the HTTP status code), the key is not stored — fix the key and test again.

Testing is done server-side (provider endpoints often block browser-origin requests), so it works for all six providers regardless of CORS restrictions.

Removing a key

Click Remove on any configured card. A confirmation prompt appears. After removal:

• The encrypted key is permanently deleted from the database.
• Future requests for that provider fall back to the platform key automatically.
• No scribe content or history is affected.

Frequently asked questions

See the BYOK entries in the FAQ for quick answers to "Do I need platform tokens if I use my own key?", "Why did a generation use my platform tokens when I have my own key?", "Can I test a key I already saved?", and "What happens if my key runs out of credit?".