Use your own AI keys #

View this page as Markdown

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 (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 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).
  • Moves only the calls you name onto your key, and leaves every other AI call on the 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 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 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 gives the members, and 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 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 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.

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 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 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.