BYOK

BYOK (bring your own key) lets you register keys from your own provider accounts and use them through the same kenari endpoint and kn- key. Your provider bills you for the tokens, your kenari balance is not charged, and usage still appears in your analytics at Rp 0. Per-search fees for Server tools such as web search still apply.

Add a key

Open BYOK & Routes in the dashboard, then the BYOK tab.
Click Add API Key.
Pick a Provider, paste your key, optionally add a Label (optional), and click Save.

kenari checks the key right after you save it and shows the result on the key’s row.

Provider not listed

Choose Custom (your own endpoint) and fill in:

Provider name: a unique name such as my-proxy. kenari lowercases it and replaces spaces with hyphens. You use this name in byok/ model ids and when you build routes.
Base URL: the base URL of your endpoint.
API type: OpenAI compatible or Anthropic.

Manage keys

Each provider you use appears as a card, with its keys listed in priority order.

Control	What it does
Check	Runs a fresh check of the key against the provider.
Browse models	Lists the models this key can reach, with Copy ID for each.
Row menu	Edit API Key, Disable or Enable, Delete API Key. With two or more keys on a provider, also Raise priority and Lower priority.

Key statuses

Every row shows one status.

Status	Meaning
Active	The key passed the check, or the check could not tell but the key served a request in the last 7 days. The row may add “used 2 h ago” or “never used”.
Cooldown N min	The provider rate-limited the key, had a temporary issue, or the key ran out of quota. It can be used again when the countdown ends.
Failing	The provider rejected the key. No requests go through it until you fix it.
Status unknown	The provider cannot be checked automatically, for example a custom endpoint with no models list. The key becomes Active after a request succeeds through it.
Not checked yet	A new key waiting for its first check.
Disabled	You turned the key off. It serves no requests until you click Enable.

kenari balance backup

Each provider card has a kenari balance backup toggle. When it is on and every key you have for that provider fails or hits a limit, kenari finishes the request on its own capacity and charges your balance at PAYG rates. If all your keys fail and backup is off, the request fails.

If the toggle is on and your balance is too low, the card warns you and shows a Top up link. The backup cannot cover requests until you add balance. See How billing works.

Fallback order

kenari tries the keys on a card from top to bottom, and moves to the next one when a key fails or hits a limit. The balance backup, when on, is always last. Use Raise priority and Lower priority to change the order.

For different models at each step, build a named route. See Routing and routes.

Use catalog models

You do not change any code. Send requests with your kn- key as usual. When the model you ask for is served by a provider you have a key for, kenari tries your key first.

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer $KENARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Use any model your provider serves

To reach any model your provider serves, including ones that are not in the kenari catalog, send its id with a byok/ prefix:

byok/<provider>/<model-id-at-your-provider>

Part	Rule
`byok`	Literal, lowercase.
`<provider>`	The provider of your key, or the Provider name of a custom endpoint. Matching ignores case.
Rest	Sent to your provider as written, including slashes and colons. Case is kept.

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer $KENARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "byok/deepseek/deepseek-v4-flash",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

The built-in providers are openai, anthropic, deepseek, xai, groq, mistral and opencode. A custom endpoint is addressed by the Provider name you gave it when you added the key. For example, a custom endpoint named my-proxy takes byok/my-proxy/<model-id-at-your-provider>.

To find the exact id, click Browse models on the key’s row and use Copy ID. This path never uses your balance. If you hold several keys for the provider, kenari tries them in priority order.

Errors

Status	Code	When
`400`	`byok_malformed_model_id`	The id after `byok/` is missing the provider or the model.
`400`	`byok_provider_not_found`	You have no key for that provider.
`403`	`byok_credential_unavailable`	You have keys for that provider, but none can serve now because they are disabled or cooling down.
`403`	`byok_spend_capped_key`	The `kn-` key you sent has a spend cap.

See Errors for the full list.

Keys with a spend cap

A key with a Spend cap, Rp (optional) cannot use byok/ models. For why, and how to limit BYOK usage instead, see Authentication and API keys.