API keys
Create keys inside a workspace and restrict them by model, source IP, expiry, and lifetime spend.
An API key authenticates your code. Each key belongs to one workspace and has one owner. You can restrict a key to limit the damage if it leaks.
Create a key#
- Open the workspace you want the key in, then API keys in the sidebar.
- Click Create API key and fill in the fields below.
- Copy the key from the confirmation. It is shown once. The console keeps only a masked version (
sk-****abcd). If you lose the key, create a new one.
Who can create keys: admins of an organization, and the owner of a personal space. Members cannot. See Roles & permissions.
| Field | What it does |
|---|---|
| Name | A label for you. It appears in the key list and in usage. |
| Owner | Who the key belongs to. Shown only to organization admins. Defaults to you. The owner must be an active member. See below. |
| Allowed models | Limit the key to specific models. Empty means every model the account can call. In the console you can pick up to 5. |
| IP allowlist | Accept requests only from these addresses. IPv4 or IPv6, single addresses or CIDR ranges, separated by commas or new lines. Empty means any address. |
| Expiry | A date after which the key stops working. Empty means it never expires. |
| Spending limit | A lifetime cap on what this key can spend, in whole dollars (at least $1). Empty means no cap. |
Use these restrictions together with a data policy and budgets. They answer different questions. See Access controls.
Owners#
The owner decides three things:
- Who can see the key. Members see only keys they own. Admins see all keys in the workspace.
- Whose budget it counts against. Spend on a key counts toward its owner's member budget.
- Whether the key still works. A key works only while its owner is an active member of the organization.
If the owner leaves or is removed, the key stops working immediately. Being invited back does not turn it on again. See Members & invitations.
Key status#
| Status | Meaning | Requests |
|---|---|---|
| Active | Enabled, not expired, owner is a member. | Work |
| Expired | The expiry date has passed. | 401 |
| Disabled | Turned off, for example because its workspace was deleted or its owner left and came back. | 401 |
| Owner removed | Its owner is no longer an active member of the organization. | 401 |
All of these return the same 401 as a key that does not exist. This is deliberate. See Errors & rate limits. The key list is where you find out why a key stopped working.
To make an expired key work again, edit it and set a later expiry.
Edit and delete#
- Edit changes the name, restrictions, expiry, and spending limit. You cannot move a key to another workspace. Fields you do not touch stay as they are.
- Revoke deletes the key. Requests with it start failing at once.
- A disabled key can be deleted, but only by an admin.
Keys and workspaces#
If you delete a workspace, every key in it is disabled. Create the keys again in another workspace if you still need them.
Good practice#
- Use one key per service or environment, so you can revoke one without touching the others.
- Set an expiry on keys you give to contractors or short-lived jobs.
- Put keys in environment variables or a secret store, never in source control.
- If a key leaks, revoke it first, then create its replacement.