API reference

API keys

4 operations.

GET /v1/api-keys

The account's API keys, newest first: active, expired and revoked, each with its scopes, who made it and when it was last used. Never a key itself.

Operation id
listApiKeys
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
api_keys.read
Assistant tool
No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).

Answers

200 The keys. application/json

Field Type Always sent Notes
api_keys array of object yes
api_keys[] object yes
api_keys[].id string yes
api_keys[].name string yes
api_keys[].display_prefix string yes The first characters of the key, to tell keys apart. Not enough to use it.
api_keys[].scopes array of string yes Permission names. The key may do exactly these.
api_keys[].state string yes Where the key stands now. A revoked key is revoked whatever its expiry. Values: active , expired , revoked .
api_keys[].created_by object yes Who made the key: a member. An older key may name another key. The key keeps working after its maker leaves.
api_keys[].created_by.type string yes Values: member , api_key .
api_keys[].created_by.id string yes
api_keys[].created_at string yes Limits: format date-time.
api_keys[].expires_at string or null yes When the key stops working, or null when it never expires. Limits: format date-time.
api_keys[].revoked_at string or null yes Limits: format date-time.
api_keys[].last_used_at string or null yes Noted at most once an hour. Limits: format date-time.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
429 Too many attempts. rate_limited

POST /v1/api-keys

Makes an API key and answers it once. Its scopes must be permissions you hold now, not only ones that reach the host linked to you, and cannot include managing keys. It expires at the time you choose, or never if you leave the expiry out.

Operation id
createApiKey
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
api_keys.manage
Retry key
Optional: send an Idempotency-Key header.
Assistant tool
No. It mints a capability, credential or secret that outlives the grant and is later checked against the member's full role (decision 0043, point 8).

Parameters

Name In Type Required Notes
Idempotency-Key header string no Caller-chosen key for a safe retry. 1 to 255 visible ASCII characters. Limits: pattern ^[\u0020-\u007E]{1,255}$.

Request body application/json, required

Field Type Required Notes
name string yes A label for the key, such as the system that will use it. Limits: at most 120 characters.
scopes array of string yes Permission names. The key may do exactly these, and you must hold each one yourself. A key cannot manage keys. Limits: 1 to 100 items.
expires_at string or null no When the key stops working. A time in the future, or null. Omit it, or send null, and the key never expires. Limits: format date-time.

Answers

201 The key, with the key itself. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
id string yes
name string yes
display_prefix string yes The first characters of the key, to tell keys apart. Not enough to use it.
scopes array of string yes Permission names. The key may do exactly these.
state string yes Where the key stands now. A revoked key is revoked whatever its expiry. Values: active , expired , revoked .
created_by object yes Who made the key: a member. An older key may name another key. The key keeps working after its maker leaves.
created_by.type string yes Values: member , api_key .
created_by.id string yes
created_at string yes Limits: format date-time.
expires_at string or null yes When the key stops working, or null when it never expires. Limits: format date-time.
revoked_at string or null yes Limits: format date-time.
last_used_at string or null yes Noted at most once an hour. Limits: format date-time.
secret string or null yes The key itself, shown this once. Send it as Authorization: Bearer <key> to the API's hostname. Null on a repeat of the same request (same Idempotency-Key): the key is never shown again, so revoke it and make another.

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
409 The same identifier was already used for a different request. This request is already running. id_conflict , request_in_progress
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

DELETE /v1/api-keys/{api_key_id}

Revokes an API key. It stops working on the next request. The key stays in the list as revoked. Revoking a revoked key changes nothing.

Operation id
revokeApiKey
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
api_keys.manage
Assistant tool
No. It deletes. A delete is never a tool (decision 0043, point 8).

Parameters

Name In Type Required Notes
api_key_id path string yes Limits: pattern ^key_[0-9a-z]{26}$.

Answers

200 The key after the revoke. application/json

Field Type Always sent Notes
id string yes
name string yes
display_prefix string yes The first characters of the key, to tell keys apart. Not enough to use it.
scopes array of string yes Permission names. The key may do exactly these.
state string yes Where the key stands now. A revoked key is revoked whatever its expiry. Values: active , expired , revoked .
created_by object yes Who made the key: a member. An older key may name another key. The key keeps working after its maker leaves.
created_by.type string yes Values: member , api_key .
created_by.id string yes
created_at string yes Limits: format date-time.
expires_at string or null yes When the key stops working, or null when it never expires. Limits: format date-time.
revoked_at string or null yes Limits: format date-time.
last_used_at string or null yes Noted at most once an hour. Limits: format date-time.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
429 Too many attempts. rate_limited

GET /v1/api-key/self

Lists only the authenticating API key's effective permission names.

Operation id
getOwnApiKeyPermissions
Who can call it
The authenticating API key, in its own account.
Credentials
API key

Answers

200 The key's permissions, without key or account details. application/json

Field Type Always sent Notes
permissions array of string yes

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
429 Too many attempts. rate_limited