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 (and does not do today)

When you save your own key for a provider:

• Your requests to that provider use your key. Cost goes to your provider account, not the platform's shared quota.
• The platform still checks your Coffeescribe token balance before starting a generation. Billing-skip for BYOK users is a planned follow-up (W34.2) that has not shipped yet. Until then, BYOK means "your key is used for the API call" — you still need platform tokens to start.

In short: today BYOK routes calls through your key; it does not yet remove the token-balance gate.

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.

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.

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 my own key?", "Is my key safe?", and "I added my key but still can't generate — why?".