Create an API key

POST/o/{org}/api-keys
View .md

Mints a key that acts as the caller (any org member) on the session routes. The secret is in this response only; it is never stored or shown again. Without expires_at the key never expires.

Authenticate with a signed-in session token (an API key cannot call this route).

Path parameters

orgstringrequired

The org's slug or id. A caller with no role in the org gets 404.

Request body

namestringrequired
at most 100 characters
scopesarray of stringoptional

Defaults to both scopes.

max_concurrentintegeroptional

Runs this key may have in progress at once.

Default 4min 1max 100
expires_atstring | nulloptional

In the future and at most one year away.

Format date-time

Responses

201The key, with its secret.
idstringrequired

key_…; use it in the key routes.

kindstringoptional

key is minted here; oauth is an MCP client a person connected by signing in. An oauth grant reaches only the MCP server, cannot be rotated and has no webhook; its expires_at is when it ends unless the client refreshes it.

One ofkeyoauth
namestringrequired
prefixstringrequired

The secret's first characters, to tell keys apart.

scopesarray of stringrequired
max_concurrentintegerrequired
webhook_urlstring | nullrequired
expires_atstring | nullrequired
Format date-time
created_byobjectrequired
2 fields
idstringrequired
emailstring | nullrequired
last_used_atstring | nullrequired
Format date-time
created_atstringrequired
Format date-time
statsobjectoptional

The runs the key started in the last seven days. Only in the list. finished counts runs that ended completed or needs_review, out of ended. webhook_deliveries is the state of each run's latest completion webhook: delivered, still being retried, or dropped after the last try.

7 fields
sincestringrequired
Format date-time
runsintegerrequired
finishedintegerrequired
endedintegerrequired
spend_usdnumberrequired
mcp_runsintegerrequired

Of runs, those started through MCP.

webhook_deliveriesobjectrequired
3 fields
deliveredintegerrequired
retryingintegerrequired
failedintegerrequired
secretstringrequired

The key's secret. Only in the create and rotate responses; never shown again.

webhook_secretstringoptional

The webhook signing secret. Only in the update response that minted it.

400An invalid field (VALIDATION_ERROR).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
404No such resource for the caller, including one in an org the caller is not in or a Project that is private to someone else.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
429The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (RATE_LIMITED).

The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (RATE_LIMITED). The error names the limit. Wait Retry-After seconds.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional

Used in