Advanced Features
Provider Keys & BYOK
Use your own provider API keys with TokSpan. Zero service fee on BYOK traffic, keep your existing provider relationships, and combine your keys with TokSpan's pool for maximum flexibility.
What is BYOK?
Bring Your Own Key (BYOK) lets you configure your existing provider API keys (OpenAI, Anthropic, Google, etc.) directly in TokSpan. When you call a model that matches a BYOK provider, TokSpan routes through your key instead of our shared pool.
With BYOK, you pay the provider directly at their rates — TokSpan adds zero service fee on BYOK requests. You still get TokSpan's unified endpoint, auto-failover, cost tracking, and rate limit management.
Why Use BYOK?
| Scenario | Benefit |
|---|---|
| You have enterprise pricing with OpenAI / Anthropic | Keep your negotiated rates, avoid double margins |
| Your organization requires direct billing per provider | Provider charges appear on your provider bill, not TokSpan |
| You need strict data policy compliance | Data flows through your keys — you control the provider relationship directly |
| You want a gradual migration path | Start with BYOK, add TokSpan pool as fallback, transition at your pace |
Setting Up BYOK
- Go to Dashboard → Settings → Provider Keys
- Click Add Provider Key
- Select the provider (OpenAI, Anthropic, Google, etc.)
- Paste your provider API key
- Optionally restrict to specific models — only those models will use this key
- Set a priority — lower numbers are tried first
Routing Logic with BYOK
When you make a request, TokSpan resolves which key to use in this order:
- BYOK keys (by priority) — Your keys are tried first if they match the requested model
- TokSpan pool — If no BYOK key matches (or all BYOK keys fail), we fall back to our shared pool
You can toggle "Always use this key" to prevent fallback to the pool — the request will error if your key fails (useful for hard data-policy requirements).
Configuration Example
A typical setup with priority-based routing:
{
"providers": {
"openai": {
"api_key": "sk-your-openai-key",
"models": ["gpt-4o", "gpt-4o-mini"],
"priority": 1
},
"anthropic": {
"api_key": "sk-ant-your-key",
"priority": 2
}
}
}In this setup: requests for GPT-4o or GPT-4o-mini use your OpenAI key (no service fee). Requests for Claude models use your Anthropic key. Everything else falls back to the TokSpan pool.
Monitoring BYOK Usage
In the Dashboard usage logs, BYOK requests are tagged with the provider key used. Filter by provider to see your direct-provider spend vs. TokSpan pool spend. Activity logs show which key served each request — useful for debugging and cost allocation.
Best Practices
- Leave fallback enabled — Unless you have a hard policy reason, let TokSpan fall back to the pool if your key fails. This is the number one reliability win.
- Set model restrictions — Scope each BYOK key to specific models to prevent accidentally routing expensive models through your key.
- Monitor provider bills — BYOK requests appear on your provider's invoice. Cross-check with TokSpan's usage logs periodically.
- Rotate BYOK keys — Same 90-day rotation policy applies. Revoke old keys from the provider dashboard, update in TokSpan.