Bring-your-own-key (BYOK)

Scenario: Your company policy requires that all LLM calls use an API key that belongs to your own Anthropic / OpenAI account so usage appears in your own billing dashboard and never routes through a third party.

Mushi Mushi supports project-scoped BYOK. When set, the classifier, judge, fix, review and intelligence-report runs for that project use your key first, so usage shows up in your provider console, not Mushi Mushi’s. This works on every plan, Free included. A diagnosis written on your own key still counts toward your plan’s diagnoses: your key moves the AI vendor’s bill to you, it does not add diagnoses.

Setup

In the admin console: Settings → AI keys.

1. Find the service’s row (Anthropic, OpenAI, OpenRouter, Cursor, Firecrawl, Browserbase or Supabase) and click Add key. You can paste OPENAI_API_KEY=sk-… or a quoted value; Mushi Mushi strips the name and quotes.
2. Click Save & validate. Mushi Mushi checks the key with the provider first (a free call), then stores it in Supabase Vault. The database row keeps only the secret’s ID, and the key is never returned to the browser.
3. Add more than one key for a service and Mushi Mushi moves to the next one when a key is rejected or runs out of quota.

One key for every app

A new key is used by All my apps by default: every app in every organization you own, so you add it once even when your apps live in several organizations. The add form’s Use this key for picker also offers This organization (every app in it) and This app only.

• Each app tries its keys in this order: its own key, its old single key from before key pools, its organization’s key, the all-apps keys of its organization’s owners, then Mushi Mushi’s own key. A shared key is a fallback or backup, never a replacement for an app’s own key.
• An all-apps key reaches only organizations where you are an owner, never one you only administer or belong to. Only you can test, turn off, change or remove it; other members see it read-only on the apps it serves.
• A key’s row shows where it is used (All my apps, All apps in …, This app only). Change it with the row’s Used by picker; the move is confirmed first and recorded in the key audit log.
• An organization key is managed by the organization’s owners and admins. Turning off or removing an organization or all-apps key affects every app that uses it, so the confirmation says so.
• Supabase access tokens always stay with one app.
• The CLI and MCP add commands add a key to one app; organization and all-apps keys are added in the console.

What uses the key

Your own keys are used first (the app’s, then your organization’s shared keys, then its owners’ all-apps keys); when there are none for a provider, Mushi Mushi’s platform key is used where the server has one. Set both Anthropic and OpenAI keys to keep every call on your accounts.

OpenRouter

OpenRouter has its own row. Calls that would go to OpenAI try your OpenAI keys first, then your OpenRouter keys, with OpenRouter’s model names (openai/gpt-5.4). Speech-to-text and fine-tuning stay on OpenAI, because OpenRouter does not offer them. The OpenRouter row also shows the key’s spending limit and usage, read from OpenRouter.

Audit trail

Key changes write a row to byok_audit_log:

select actor_user_id, action, provider, ts
from public.byok_audit_log
where project_id = 'YOUR_PROJECT_ID'
order by ts desc;

action is one of added, rotated, removed, used, tested.

Rotation

1. Generate a new key in your provider dashboard.
2. Paste it into Settings → AI keys and save.
3. The new key is active on the next LLM call.
4. Revoke the old key from your provider dashboard once you confirm calls are flowing.

Which key a call used

Every model call is recorded in llm_invocations with key_source set to byok (one of your keys) or env (Mushi Mushi’s platform key). The console’s cost views count BYOK calls from this column.