# Bring your own keys

> Use your own provider keys with Clonvo, and what it costs.

Bring your own key (BYOK) lets Clonvo send requests through your own provider account. You keep your provider’s pricing, limits and terms; Clonvo still gives you one API, fallbacks, usage tracking and spending limits.

> **Note: Available from Pay as you go up**
> 
> On the [Free plan](https://clonvo.com/docs/plans.md), your own keys aren’t used: requests to paid models fail with `402` and the code `byok_requires_paid_plan`, even if you’ve added keys. Buy credits of any amount to move to Pay as you go.

## Supported providers

OpenAI, Anthropic, Google AI Studio, xAI, DeepSeek, Mistral, Moonshot AI (Kimi), Meta and Alibaba Cloud (Qwen). For Alibaba Cloud, use a key from the Singapore (international) region. Free models run on Clonvo’s OpenRouter account and can’t use your key.

## Tool providers

[Tools](https://clonvo.com/docs/tools.md) such as `web_search` and `web_scrape` use your own Firecrawl, Tavily, Exa, Parallel or TinyFish key, added under **Provider keys → Tools**. Add your own keys to use your accounts; otherwise calls run on Clonvo credits, through treg, at the call’s cost plus 2%. Tool keys work like model keys, with two differences:

-   Clonvo tries your tool keys first, provider by provider. When they all fail with an error worth retrying, or you have none, the call runs on Clonvo credits through treg, unless you exclude `treg` in the call’s `provider` settings.
-   **Always use this key** on a tool key stops Clonvo from moving on to another tool provider, or to Clonvo credits, when that key fails.

Each call on your key counts its list price toward the same monthly allowance as your model keys, and the BYOK fee applies above it, as described under [Pricing](#pricing). Calls on Clonvo credits don’t count toward the allowance; see [Tools billing](https://clonvo.com/docs/tools.md#billing). TinyFish charges nothing for search and page reads within its daily limits, so TinyFish calls have a list price of $0 and never count toward the allowance or the fee.

## Providers that need your own key

Some providers aren’t available on Clonvo credits yet. Their models run only with your own key for that provider. Without one, requests fail with `400` and the code `provider_requires_own_key`, and the playground’s model picker marks those models **Needs your own key**. Add a key under **Provider keys** and they work like any other model.

## Adding a key

1.  Create a key in your provider’s console. Each [model page](https://clonvo.com/models.md) links to the right place.
2.  In the Clonvo dashboard, open **Provider keys** and add it. You need to be an owner or admin of the organization.
3.  Send requests as usual with your Clonvo API key. Nothing changes in your code.

Provider keys are encrypted at rest (AES-256-GCM) and are never shown again after you save them; the dashboard shows a masked form. They belong to the organization and are used for requests from all its projects.

## How requests are routed

For a model whose provider has one of your keys, Clonvo uses your key first. If it fails with a rate limit, server error, timeout or authentication error, Clonvo retries on Clonvo credits (when the provider is available on credits), unless the key is set to **Always use this key**. See [Fallbacks and routing](https://clonvo.com/docs/fallbacks.md#credentials-your-keys-first-then-credits).

With several keys for the same provider, Clonvo tries them in the order you added them, oldest first, and moves to the next one only when a key fails. It doesn’t spread requests across keys. Disabled keys are skipped.

The response tells you which was used: `usage.is_byok` is `true` when your key served the request. `usage.cost` still shows the list price, so you can compare it with what the request would have cost on credits.

## Pricing

The terms below apply on Pay as you go. On Enterprise, the allowance and rate are agreed with your organization.

| Usage on your keys this month (UTC) | Clonvo fee |
| --- | --- |
| First $25,000 at list price | None |
| Above $25,000 | 4% of what the request would have cost on credits |

The provider bills you directly for tokens. Clonvo’s fee, when it applies, is deducted from your organization’s credit balance, so keep some credits if you expect to pass the allowance. Once you’re past the allowance with a balance of zero or less, requests on your keys fail with `402` and the code `byok_fee_requires_credits` until you buy credits. The [pricing page](https://clonvo.com/pricing.md#byok) has worked examples.

## What your provider sees

Requests arrive at your provider from Clonvo’s servers, authenticated with your key. Your provider’s data policy and retention apply as for any API request on your account; model pages link to each provider’s policy.

## Removing a key

Delete the key in **Provider keys**. Requests switch to Clonvo credits within about 15 seconds. Revoke the key in your provider’s console too if you no longer need it.