# Providers

The **Providers & Routes** page in the dashboard, tab **Providers**, is where you bring your own accounts to kenari. There are two kinds. An API key is a key from a provider account you pay per token. An AI subscription is a login to a plan you already pay for, such as ChatGPT Plus or Pro, Claude Max or Team credits, or SuperGrok. You call both through the same endpoints and the same `kn-` key.

Requests served by your own key or subscription cost Rp 0 on kenari. The provider bills you, your kenari balance is not touched, and usage still appears in your analytics. When a key or subscription cannot serve a request, a [route](/en/docs/routing) can continue on your balance. Per-search fees for [Server tools](/en/docs/server-tools) such as web search still apply.

BYOK (bring your own key) is the name of the model id prefix `byok/`, which addresses these accounts. It is not a dashboard page name any more.

## API keys

### Add a key

1. Open **Providers & Routes** in the dashboard, then the **Providers** tab.
2. In the **API keys** section, click **Add API Key**.
3. Choose a **Provider**, paste the key, add a **Label (optional)** if you want, then click **Save**.

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

The names `chatgpt` and `grok` are taken by subscription logins, so you cannot add an API key under them.

#### Your provider is not in the list

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 in priority order.

| Control | What it does |
| --- | --- |
| **Check** | Checks the key against the provider again. |
| **Browse models** | Shows the models this key can reach, with **Copy ID** for each one. |
| Row menu | **Edit API Key**, **Copy key ID**, **Disable** or **Enable**, **Delete API Key**. When a provider has two or more keys, it also has **Raise priority** and **Lower priority**. |

#### Key status

Each row shows one status.

| Status | Meaning |
| --- | --- |
| **Active** | The key passed its check, or the check could not confirm but the key served a request in the last 7 days. The row can add "used 2 h ago" or "never used". |
| **Cooldown N min** | The provider rate limits the key, has a temporary problem, or the key's quota ran out. The key becomes usable again on its own when the pause ends. |
| **Failing** | The provider rejects the key. No request goes through this key until you fix it. |
| **Status unknown** | The provider cannot be checked automatically, for example a custom endpoint with no model list. The key becomes **Active** after a request succeeds through it. |
| **Not checked yet** | A new key waiting for its first check. |
| **Inactive** | You turned this key off. It serves no requests until you click **Enable**. |

### kenari balance backup

Each API key provider card has a **kenari balance backup** switch. 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. When every key fails and the backup is off, the request fails.

If the switch is on but your balance is too low, the card shows a warning and a **Top up** link. The backup cannot cover requests until you add balance. See [How billing works](/en/docs/billing).

The backup belongs to API keys. A request to a `byok/chatgpt/...` or `byok/grok/...` id never reaches your balance. To continue on your balance after a subscription, use a [route](#use-a-connection-in-a-route).

### Fallback order

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

### Use a catalog model

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 whose key you saved, kenari tries your key first.

```bash
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!"}]
  }'
```

A subscription login is not used for catalog models. Address it with a `byok/` id or a route.

## AI subscriptions

The **AI subscriptions** section above the API keys has one tile each for ChatGPT, Claude and Grok. Connect a subscription and kenari shows it as a card, with its state and quota.

You can connect up to 5 ChatGPT and Grok logins in total, and one login for each upstream account. Connecting the same ChatGPT or Grok account again replaces its login instead of adding a second one. Claude credits are an ordinary API key, so they do not count toward the 5.

### Members only

ChatGPT and Grok need an active plan. The tile of a non-member shows **For plan subscribers** and a **See plans** link. A trial or a gifted plan counts as an active plan. See [Subscriptions](/en/docs/subscriptions).

If your plan lapses, your logins stay stored and their cards show **Needs an active plan**. kenari skips them, a `byok/chatgpt/...` or `byok/grok/...` request returns `403` and `subscription_required`, and a route skips their steps and continues with the next one. Renew your plan and they work again. kenari keeps refreshing a login that was used or connected in the last 30 days, so a short lapse does not sign you out.

Claude credits are an API key, so adding them is open to everyone. The [Claude Managed Agents](/en/docs/claude-managed-agents) passthrough needs an active plan.

### Connect ChatGPT

Use the Codex allowance in your Plus or Pro plan.

1. On the **ChatGPT** tile, click **Connect**.
2. Read the note, then click **Start**. kenari shows a code in **Your code**.
3. Click **Open ChatGPT**. This opens `https://auth.openai.com/codex/device` in a new tab. Sign in to your ChatGPT account and enter the code.
4. Go back to the dashboard. It shows **Waiting for confirmation** until OpenAI approves, then **ChatGPT connected**.

The code is valid for a limited time and the dialog shows how long is left. If the code expires or you cancel the sign-in, click **Try again** for a new code.

<aside class="warn"><strong>Warning</strong> This login uses your ChatGPT account through kenari. OpenAI may limit accounts used outside its own apps.</aside>

### Connect Grok

Use the allowance in your SuperGrok or X Premium+ plan.

1. On the **Grok** tile, click **Connect**, then **Start**.
2. Click **Open Grok**. This opens the xAI device page at `https://accounts.x.ai/oauth2/device`. Sign in to your xAI account and enter the code.
3. Go back to the dashboard and wait for **Grok connected**.

xAI decides which plans can use this access. If your plan cannot, the card shows **Your Grok plan does not support this access yet**.

### Connect Claude credits

Claude credits are the monthly API credit in a Max or Team plan. They are spent with an ordinary API key from the Anthropic Console, so there is no sign-in code.

1. On the **Claude** tile, click **Connect**.
2. Open claude.ai, then Settings, then Billing, and choose **Link organization** under API credits.
3. Open platform.claude.com, then API keys, and create a new key in that organization.
4. Paste the key into the dialog.
5. Choose your **Plan**: **Max 5x ($100/month)**, **Max 20x ($200/month)**, **Team** or **Other**. For **Team** and **Other**, enter **Credit per month (USD)**, from $1 to $500.
6. Set the **Renewal day**, which is the day your credit renews each month.
7. Leave **Stop automatically when credit runs out** on, or turn it off. It is on by default.

See [Credit estimate and auto-stop](#credit-estimate-and-auto-stop) for what the card shows and what the switch does.

The key is saved as an `anthropic` API key. Use it with `byok/anthropic/<model>`, and with the [Claude Managed Agents](/en/docs/claude-managed-agents) passthrough. Choose **Edit credit** on the card to change the plan or the renewal day later.

### Credit estimate and auto-stop

kenari cannot read your credit balance from Anthropic, so the card shows an estimate. It adds up the requests kenari sent with that key during the current period, valued at Anthropic's list price for each model. It does not know about anything else.

- The period starts on your **Renewal day** at 00:00 UTC and lasts until the next renewal day. When it renews, the estimate starts again from zero.
- A request shows up in the estimate within about 10 seconds.
- When **Stop automatically when credit runs out** is on, a model that has no list price is counted at the most expensive Anthropic list price, so the estimate errs on the high side. When it is off, such a model counts as zero.

When the estimate reaches your monthly credit and the switch is on, kenari skips that key, the same way it skips a paused key. A route continues with its next step, and the last step can be **kenari balance (PAYG)**. A request to `byok/anthropic/...` fails with `403` and `byok_credential_unavailable` when you have no other Anthropic key that can serve it. kenari checks the estimate about every 15 seconds, so a few requests can still go through right after the credit is used up. The key works again when the period renews. You can also raise the credit with **Edit credit**, or turn the switch off.

<aside class="warn"><strong>Warning</strong> The estimate is not a guarantee. It does not count usage that does not go through kenari, and it does not count the <a href="/en/docs/claude-managed-agents">Claude Managed Agents</a> passthrough. The only hard limit is a spend limit you set in the Claude Console, which Anthropic enforces. Set one.</aside>

### Disconnect

Open the card menu and choose **Disconnect**. kenari removes the login and stops using your subscription. You can connect it again any time.

### Card states

| State | Meaning |
| --- | --- |
| **Connected** | The login works. |
| **Limited until** a time | The subscription hit a limit, or the provider has a temporary problem. kenari skips it until that time. |
| **Needs reconnecting** | The login was rejected and cannot be refreshed. Connect it again from its tile and sign in with the same account. |
| **Needs an active plan** | Your plan has lapsed. See [Members only](#members-only). |
| **Your Grok plan does not support this access yet** | xAI refused the access for your plan. |

## Model ids

Address a connection or key with a `byok/` id:

```text
byok/<provider>/<model-at-your-provider>
```

| Part | Rule |
| --- | --- |
| `byok` | Literal, lowercase. |
| `<provider>` | `chatgpt`, `grok` or `anthropic` for the three subscriptions, otherwise the provider of your key, or the **Provider name** of a custom endpoint. Matching ignores case. |
| The rest | Sent to the provider as is, including slashes and colons. Case is kept. |

The built-in key providers are `openai`, `anthropic`, `deepseek`, `xai`, `groq`, `mistral` and `opencode`. A custom endpoint named `my-proxy` uses `byok/my-proxy/<model-at-your-provider>`.

To find the exact id, use **Browse models** on a key row or on a subscription card, then **Copy ID**. These requests never use your balance. If you have several keys or connections for the provider, kenari tries them in priority order.

All three API formats accept these ids: [Chat completions](/en/docs/chat), [Messages](/en/docs/messages) and [Responses](/en/docs/responses).

### ChatGPT

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

### Grok

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

### Claude credits

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

The same ids work on `POST /v1/messages`:

```bash
curl https://kenari.id/v1/messages \
  -H "x-api-key: $KENARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "byok/anthropic/claude-sonnet-5-5",
    "max_tokens": 512,
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## Use a connection in a route

A connection does not serve catalog models by itself. To let a subscription run first and your balance take over after it, build a [route](/en/docs/routing):

1. Open the **Routes** tab and create a custom route, or edit one.
2. Add a step. Under **Credential**, pick the connection, which is listed by provider and account, such as the ChatGPT account you connected. In **Model**, enter the provider's own model id, without the `byok/chatgpt/` prefix.
3. Add a last step with **Credential** set to **kenari balance (PAYG)** and a model kenari serves.
4. Save, then send the route name as `model`.

A step is one connection plus one model. kenari tries the steps in order. A step whose connection is paused, disabled, signed out or lapsed is skipped, and the next step serves. The balance step is the only one that charges your balance.

## Quota

A ChatGPT or Grok card shows how much of your allowance is left. The bars show what remains.

| Card | What it shows |
| --- | --- |
| ChatGPT | **5-hour session** and **Weekly**. Each window shows the share left and when it resets. |
| Grok | **Credit this period**, with the share left and **Period ends** with the date. |
| Claude | **Credit this month (estimate)**, with the amount spent out of your monthly credit and the renewal date. It is kenari's own estimate, see [Credit estimate and auto-stop](#credit-estimate-and-auto-stop). The card also shows whether auto-stop is on. |

kenari reads the figures when you open the page and keeps them for 60 seconds. When a figure is old, the card shows how long ago it was updated and a refresh button. **Check quota** in the card menu refreshes it too. When kenari cannot read the quota, the card says **Quota not available yet**. Your requests are not affected by this.

Under the bars, each subscription card also shows a usage line, such as "1,240 requests, 3.2M tokens in 30 days". It counts the requests kenari served with that connection over the last 30 days, and the tokens are input plus output. The line appears after the connection has served its first request, and it is updated within about 10 seconds.

When a subscription answers that its allowance is used up, kenari pauses that connection until the window resets. The card shows **Limited until** with the time, and routes continue with the next step.

## Errors

These are the errors you can see around this page. The full list is in [Errors](/en/docs/errors).

### Requests

| Status | Code | When |
| --- | --- | --- |
| `400` | `byok_malformed_model_id` | The id after `byok/` has no provider or no model. |
| `400` | `byok_provider_not_found` | You have no key or connection for that provider. |
| `403` | `subscription_required` | A `byok/chatgpt/...` or `byok/grok/...` request from an account without an active plan. |
| `403` | `byok_credential_unavailable` | You have a key or connection for that provider, but none can serve now because it is disabled, paused, or signed out. |
| `403` | `byok_spend_capped_key` | The `kn-` key you sent has a spend cap. |

### Dashboard

These codes come from the dashboard while you connect a subscription or read its quota. The dashboard turns them into the messages you see.

| Status | Code | When |
| --- | --- | --- |
| `400` | `provider_unsupported` | You tried to connect a provider other than ChatGPT or Grok, or the provider is unavailable for now. |
| `403` | `subscription_required` | Connecting or reading the quota needs an active plan. |
| `409` | `limit_reached` | You already have 5 connected subscriptions. At the limit you can still sign in again to replace a login that needs reconnecting. |
| `429` | `rate_limited` | Too many sign-in attempts in an hour, or too many quota refreshes. Try again later. |
| `503` | `quota_unavailable` | kenari could not read the quota and has no earlier figure to show. |

## Keys with a spend cap

A key with a **Spend cap, Rp (optional)** cannot use `byok/` models. The reason, and how to limit BYOK usage, is in [Authentication and API keys](/en/docs/authentication).

## See also

- [Routing and routes](/en/docs/routing)
- [Claude Managed Agents](/en/docs/claude-managed-agents)
- [Subscriptions](/en/docs/subscriptions)
- [Authentication and API keys](/en/docs/authentication)
- [How billing works](/en/docs/billing)
- [Errors](/en/docs/errors)