Bring your own provider key

BYOK — Bring Your Own Key — lets you plug in a provider key you already have (Anthropic, OpenAI, Gemini, and more) and have that provider bill you directly for model usage. Alumia still records the request as BYOK and meters the platform fee after the $100 waiver, plus any separate infrastructure, storage, or collaboration usage.

1. Open Billing

Navigate to /<orgSlug>/billing. Scroll to the BYOK keys section. This is the only place keys are managed; agent edit pages and the lab do not let you paste keys inline.

2. Add a key

Click Add key. The dialog asks for two things:

• Provider — one of: anthropic, openai, gemini, deepseek, xai, mistral, minimax, moonshot, zhipu, xiaomi, nvidia, qwen, cerebras, groq.
• API key — the secret from the provider's console (e.g. sk-ant-... for Anthropic, sk-... for OpenAI).

Submit. The key is encrypted at rest, and the dashboard only ever shows a masked prefix afterward.

3. How routing works

BYOK matches by provider, not by model. When an agent runs a model whose provider has an active BYOK key in your org, the request goes through that key. There is no per-agent toggle: enabling BYOK for anthropic immediately covers every Claude model the agents use.

If no BYOK key exists for the model's provider, the request goes through the platform's own provider account and is metered against your Alumia balance.

4. How billing changes

For BYOK requests:

• The provider bills you directly for the model tokens. The provider token cost does not draw from your Alumia balance.
• Usage is recorded with the byok flag on the org's metrics, visible in /<orgSlug>/billing under the BYOK request count.
• After the $100 platform-fee waiver, Alumia meters the 5.5% platform fee on the equivalent provider list price.
• Platform infrastructure (storage, browser sessions, sandboxes, collaboration) continues to be metered against your Alumia balance regardless of BYOK.

For non-BYOK requests, see Billing for the standard pay-as-you-go pricing, the early-bird $10 signup credit, and the $100 platform-fee waiver.

5. Deactivate a key

In the BYOK section, find the key in the list and click Deactivate. The next request for that provider falls back to the platform's account immediately. Deactivation is reversible — you can add the same key again later.

6. Free providers stay free

Groq, NVIDIA, and other zero-cost providers in the model catalog work without any key, BYOK or otherwise. You only need BYOK for paid providers you want to bill yourself.

Verify it's working

Open the lab, pick a model whose provider has a BYOK key, send a message, and check /<orgSlug>/billing. The BYOK request count goes up; provider token cost is billed by the provider, while Alumia balance reflects any applicable platform fee or separate metered app usage.