API reference · API keys
Create an API key (the secret is returned once)
/v1/api-keysCreates a key that acts inside this project with the scopes you give it, which may not exceed what your own role grants. The secret appears only in this response and cannot be read again; a replay with the same Idempotency-Key returns the same response.
Console session only: no API key can be granted the api_key:create permission it needs. Requires the api_key:create permission (a key's scope, or a role that includes it).
Request
| Header | Required | Description |
|---|---|---|
X-Project-Id | yes | The project to act in, for console sessions. Requests with an API key leave it out. |
Idempotency-Key | no | Makes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you. |
Body
JSON (application/json): CreateApiKeyRequest.
namestringrequiredIts name
1–100 characters
scopesarray of stringrequiredActions (`resource:verb`) or `resource:*`; at most your own role grants
1–100 items
expires_atstring (date-time) | nullWhen it expires (null: never) (ISO 8601, UTC)
Response
201 CreatedApiKey — The new key, including its secret
objectstringrequiredAlways `api_key`: the type of this object
One of
api_keyidstringrequiredUnique ID (`key_…`)
ID with prefix key_
org_idstringrequiredOrganization it belongs to
ID with prefix org_
project_idstringrequiredProject it belongs to
ID with prefix prj_
namestringrequiredIts name
scopesarray of stringrequiredActions (`resource:verb` or `resource:*`) the key may perform, as granted
last4stringrequiredLast four characters of the secret, for display
statusstringrequired`active`: usable; `revoked`: revoked and refused from then on; `expired`: past `expires_at` and refused
One of
activerevokedexpiredexpires_atstring (date-time) | nullrequiredWhen it expires (null: never) (ISO 8601, UTC)
last_used_atstring (date-time) | nullrequiredUpdated at most once a minute
revoked_atstring (date-time) | nullrequiredWhen it was revoked (null while it is valid) (ISO 8601, UTC)
created_by_user_idstring | nullrequiredID of the user who created it
created_byobject | nullrequiredWho created it (null: created by the platform)
ShowHide 3 fields of
created_byobjectstringrequiredAlways `person`
One of
personidstringrequiredThe person’s user ID (`usr_…`)
namestring | nullrequiredTheir name as they set it; null when they are no longer a member of the organization
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
updated_atstring (date-time)requiredWhen it last changed (ISO 8601, UTC)
secretstringrequiredThe API key. Returned only in this response; store it now.
Example response
{
"object": "api_key",
"id": "key_01jc5zq4m8k3v6x9t2w7r0b1e4",
"org_id": "org_01jc5zq4m8k3v6x9t2w7r0b1e4",
"project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"name": "string",
"scopes": [
"ssh_key:read",
"inference:invoke"
],
"last4": "string",
"status": "active",
"expires_at": "2026-01-01T00:00:00.000Z",
"last_used_at": "2026-01-01T00:00:00.000Z",
"revoked_at": "2026-01-01T00:00:00.000Z",
"created_by_user_id": "string",
"created_by": {
"object": "person",
"id": "string",
"name": "string"
},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"secret": "sk_01jc5zq4m8k3v6x9t2w7r0b1e4_…"
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
409 | conflict_error idempotency_in_progress | A request with the same Idempotency-Key is still running. |
422 | idempotency_error idempotency_key_reused | The Idempotency-Key was used with a different request. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |