Bring your own key

Bring your own key (BYOK) lets Router use your provider API keys for your requests. Keys are scoped per user and provider, with exactly one key per provider. There is no organization-level key tier.

Router supports keys for OpenAI, Fireworks, and xAI.

Add a key

Manage keys from Manage provider keys on the API keys page. Keys are write-only, so you cannot view them after saving. You can also configure optional residency settings for supported providers.

Key settings

• Enabled — On by default for a new key. Turn it off and Router ignores the key entirely; your requests use only the shared Router key.
• Shared key fallback — On by default. When on, if your key fails with an authentication error, rate limit, provider outage, or a similar fallback-triggering error, Router retries the same model with its shared key. Turning it off disables the shared-key retry for that provider. Provider errors then follow normal model fallback, and a later candidate on the same provider still uses your key.

Key precedence

For each provider candidate, Router tries credentials in this order:

1. Your enabled provider key for that provider.
2. Router's shared key for that provider.

If neither exists, that provider is unavailable for your requests. A disabled key is ignored entirely, so requests use only the shared key.

When Router falls back to a shared key

With Shared key fallback on, if your key fails with 401, 403, 429, any 5xx, a network error or timeout, or a key-decryption failure, Router retries the same model with its shared key. Other provider 4xx errors do not trigger a shared-key retry; instead, they follow normal model fallback behavior.

Key fallback retries a model with another credential. Model fallback advances to another candidate. See Errors and limits for how failures surface.

For streaming requests, key fallback can happen only before the response produces billable output. Once output starts streaming, Router stays on that key.

Request logs record the credential that served the request as credential_source (byok or shared) and whether a fallback occurred as key_fallback_used.

Billing

When Router serves a request with your key, the provider bills you directly and Router does not charge for it. Router still displays the provider's list cost as an estimate in logs and usage.

When a request falls back to Router's shared key, Router bills it normally.

Security and key lifecycle

Keys are write-only and stored encrypted. You cannot view a key after saving it.

Router does not call the provider to validate a key when you save it. An invalid key is not automatically disabled and continues to be tried until you replace, disable, or delete it.

Adding, replacing, disabling, or deleting a key propagates asynchronously and may take a short time to apply to new requests.

Data residency

OpenAI keys accept an optional data-residency region: global, US, or EU. Select the region of the OpenAI project that issued the key.