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
|