Create a key in the dashboard
On API Keys, select Create API Key and enter a name, an optional credit limit with how often it resets, and an expiry. The expiry is never, 7, 30 or 90 days, or a date you pick. The key goes to the workspace you picked at the top of the dashboard. To create it elsewhere, switch to that workspace first. Through the API, you name the workspace inworkspace_id, and without it the key goes to Default.
The dashboard shows the new key once. Next to it is a first request to the Responses API in Python and cURL, with your key filled in. The request targets the newest :free chat model. While your balance is zero, a line under it gives the free-model daily limit and links to Credits. Every model without :free needs credits. The list shows each key’s usage and limit and the day of its last request, newest key first. It marks a key that can’t be used as Disabled, Expired or Limit reached. Days are in UTC, and a key with no requests shows Never. The row menu renames, limits, disables, enables or deletes a key.
Create a key with the API
The account API takes a provisioning key, not an API key. Onlyname is required.
key, and no later response shows it again, so store it right away:
expires_at must be in the future.
Choose key settings
A key carries the settings listed here. All but the default routing strategy exist in the dashboard and the API. You can set the default routing strategy only through the API.Limit spending per day, week or month
A key withcredit_limit_period set to day, week or month gets its full credit limit again at the start of each period. A nightly job can then spend $5 a day without anyone raising the limit every morning. Periods run in UTC: a day starts at midnight, a week on Monday and a month on its first day. With all, the limit covers everything the key ever spends.
The limit is checked before each request, and the request then costs what it costs. A request that starts with room left can take the key past its limit, and so can several requests running at once. Size the limit with your largest request in mind.
The limit counts only paid spend. A request to a free model, one whose id ends in :free, costs nothing, so it goes through even when the key’s limit or a budget is spent. Free models have their own daily request limit. A key with a credit_limit of 0 is therefore a key for free models only.
Changing the period starts the count over from zero at the moment of the change. Changing only the amount keeps what the key has spent in the current period.
Change, disable or delete a key
The account API has five key operations. The list comes newest first and includes disabled and expired keys. Add?workspace_id= to list one workspace’s keys.
PATCH changes only the fields you send. Send null to clear credit_limit, expires_at or default_routing_strategy, or to move the key to Default with workspace_id. name, is_enabled and credit_limit_period can’t be null. Disabling is the quick way to stop a leaked key, and you can enable it again later.
Put keys in workspaces with the API
A workspace groups keys by product, environment or client. Admins create, rename and archive workspaces in the dashboard. A provisioning key reads them and places keys in them, which lets a deploy script give each environment its own key in the right workspace.GET /v1/account/workspaces lists the named workspaces you can put keys in, oldest first. Default isn’t in the list, because it has no id: a key in Default has workspace_id: null. Archived workspaces aren’t listed either: their keys keep their workspace_id and stay disabled.
id as workspace_id when you create a key, to put it there, or in PATCH to move a key. A moved key keeps its secret, limit and spend. Leaving workspace_id out of a new key puts it in Default.
GET /v1/account/keys?workspace_id=3 lists the keys of one workspace, and ?workspace_id=default the keys in Default. The same parameter on GET /v1/account/activity reports the spend of one workspace.
Rotate a key
There’s no rotate action. To rotate a key, create a new one, move your clients to it, and delete the old one after nothing uses it. Creating the new key first means your clients never run without a valid key.Troubleshooting
403 credit_limit_exceeded
The key has spent its credit limit and the request is for a paid model. Free models still answer. For a key with a period, the message says when the limit resets:
credit_limit on the key, or use a key with room left. Only an organization admin raises a budget.
403 model_not_allowed
The organization or the key’s workspace allows only some models, and this one isn’t among them. The message says which list refused it and where an admin changes it:
GET /v1/models called with the same key, which lists only the allowed ones, or ask an admin to allow the model.
401 expired_api_key
The key’s expiry has passed. Clear or move expires_at, or create a new key.
401 disabled_api_key
Someone disabled the key. Set is_enabled to true, or enable it from the row menu in the dashboard.
400 API key not found
Thekey_id doesn’t exist on the account. List the keys with GET /v1/account/keys and use an id from the result.
400 workspace not found
Theworkspace_id in the body isn’t a workspace of the account, for example one from another organization or a number too large to be a workspace id. List the workspaces with GET /v1/account/workspaces and use an id from the result, or send null for Default.
400 workspace is archived
The key would be enabled in an archived workspace, which keeps its keys disabled. The message names the field:workspace_id when you put the key there, is_enabled when you turn on a key that is already there. Put the key in a live workspace from GET /v1/account/workspaces, or in Default with null, and enable it there.