--- title: Use your own AI keys description: Run your application's AI calls on your own Anthropic, OpenAI, Google, or xAI key, billed by that provider, beside the plan's included AI allowance. slug: /guides/use-your-own-ai-keys order: 37 visibility: public redirects_from: [] --- # Use your own AI keys Prompt: > Use my own OpenAI key for the chat feature. I stored it on the Turn Zero dashboard as OPENAI_KEY. Also works: - "Run the summaries on Claude with my Anthropic key, stored as ANTHROPIC_KEY, and keep the included allowance for the titles." - "When the month's AI allowance runs out, switch to my own key." ## What your tool does - Confirms the key's name with `list_secrets`. Where the key is not stored, it follows the `store-key` [skill](/concepts/glossary#skill) (`read_context`, id `skill:store-key`). - Declares the provider as an upstream with `declare_upstream`, naming the stored key, as [Call an external API with an API key](/guides/call-an-external-api-with-an-api-key) shows. - Leaves a provider's own software development kit (SDK) unchanged where your code uses one, and declares the upstream with `sdk_settings` ([An unchanged SDK](/guides/call-an-external-api-with-an-api-key#an-unchanged-sdk)). - Moves only the calls you name onto your key, and leaves every other AI call on the [AI allowance](/concepts/glossary#ai-allowance). - Deploys and reads `read_status` until the deploy ends. - Asks you for the name you stored the key under and which calls move to it, where the prompt does not say. ## What you need - An API key from your AI provider. Anthropic, OpenAI, Google, and xAI are supported at launch. Your application names the provider and the model on each call. - The key stored on the Turn Zero dashboard under a name, such as `OPENAI_KEY`, as [Store a secret](/getting-started/store-a-secret) shows. The value is write-only: nobody can read it back, your AI included. ## Before your AI starts This section is for your AI coding tool: what it checks and gathers before it begins. You don't need to do these steps yourself. - Name the provider and the model on each call. Anthropic, OpenAI, Google, and xAI are supported at launch. - Choose the route on each call. A call through the person's upstream runs on their stored key and draws no allowance; a call through the allowance draws the plan's dollars. A stored key never replaces the allowance and never turns it off. - Move only the calls the person names onto their key, and leave every other AI call where it is. ## Steps ### 1. Store your key Store the provider's key on the dashboard, or ask your AI to store it, as [Store a secret](/getting-started/store-a-secret) shows. The key never enters your code, your chat, or your application's container: the platform keeps it and adds it to each call on its way out. To replace it later, store the new key under the same name, and the next calls use it with no redeploy. ### 2. Declare the provider's upstream Your AI declares one upstream for each provider, naming the provider's API address, the header its key goes in, and the stored key's name. [Declare the upstream](/guides/call-an-external-api-with-an-api-key#2-declare-the-upstream) gives the members, and [An unchanged SDK](/guides/call-an-external-api-with-an-api-key#an-unchanged-sdk) gives the settings the OpenAI and Anthropic SDKs read. ### 3. Call the model Your code calls the provider's own API paths through the upstream, either with the [Egress](/backend-packages/egress) package's client or with the provider's SDK unchanged. The answer is the provider's own, passed back as it came. Your provider bills you directly, on your own provider account, and Turn Zero adds no markup and resells no AI usage. ### 4. Choose the route for each call Keep a call on the allowance with the [AI Allowance](/backend-packages/ai-allowance) package, or send it through your upstream. The allowance never bills overage: once the month's allowance is used, its calls are refused until the month resets. To fall back to your key then, follow [Fall back when the allowance runs out](/guides/call-an-ai-model-under-the-allowance#5-fall-back-when-the-allowance-runs-out). ## Expected result The calls you moved run on your key and appear on your provider's bill, and the allowance's remaining dollars stay the same for them. The platform counts each call per upstream in your application's usage. ## Refusals This table lists the refusals these steps most often meet; the [refusals page](/reference/refusals) lists all of the platform's refusals, with the cause and remedy of each. A backend package's own failures are listed on its package page. [Call an external API with an API key](/guides/call-an-external-api-with-an-api-key#refusals) lists the gateway's other refusals. A refusal from the provider itself, such as an invalid key or the provider's own rate limit, comes back unchanged. | Refusal | Status | Cause | Remedy | | --- | --- | --- | --- | | `credential_not_in_custody` | 409 | The `credential_name` is not stored at a scope the upstream can use. At a call, `detail` says when it is stored for the other environment alone. | Store the key under that name with `store_secret`, at this environment's scope or at account scope, then retry. | | `undeclared_upstream` | 404 | Your account declares no upstream by that name. | Declare it, or call the name you declared. | | `upstream_unreachable` | 502 | The connection to the upstream failed; `detail` gives the error code. | Retry, and check the base URL and the upstream's own status. | | `egress_daily_bytes_capped` | 429 | The application passed its plan's outbound bytes for the UTC day. The body includes `count`, `limit`, and `resets_at`. | Wait for `resets_at`, or move to a larger plan with `set_plan`. | | `allowance_exhausted` | 429 | This UTC month's allowance is used up; the refusal includes `resets_at`, `used`, and `quota`. | Wait for `resets_at`, move to a larger plan, or call your own upstream. Retrying this month is refused and counted each time. | ## Related - [Call an external API with an API key](/guides/call-an-external-api-with-an-api-key) declares an upstream and calls it, with samples. - [Call an AI model under the allowance](/guides/call-an-ai-model-under-the-allowance) uses the plan's included allowance. - [Egress](/backend-packages/egress) is the client for calls on your stored keys. - [AI Allowance](/backend-packages/ai-allowance) is the client for the included allowance. - [Store a secret](/getting-started/store-a-secret) stores and replaces a key.