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 pay that provider directly for model usage. The platform keeps metering its own infrastructure, storage, and collaboration features separately, but the LLM line item moves off your Alumia balance.

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. Token usage 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.
• The 5.5% platform fee does not apply to BYOK token cost — it never touches Alumia's balance.
• 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; the spent balance does not change.