Keys of the account's members, people and Agents. The overview covers what every operation shares: authentication, roles, errors, pagination, idempotency and If-Match.
GET /api-keys List your keys, or every key of the account for an owner or admin
POST /api-keys Create a key; its secret is in this answer only
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
Needs api_keys.own, which owner, admin and member hold. A narrowed key may not.
A personal key acts as you; an Agent key (member: agent.<agent id>), which owners and admins create, acts as the Agent, whose role may not exceed yours. read_only, and either buckets or any of databases, database_prefixes, streams and stream_prefixes, narrow the key for its whole life: a different narrowing takes a new key. An access token never creates a key, and neither does a narrowed key.
Request body
application/json, required. Unknown fields are refused.
Field
Type
Required
Description
name
string
yes
A name to tell the key apart, 1 to 80 characters once spaces are trimmed; unique, ignoring case, among the member's live keys, so a second live key with the name answers 409. 1 to 80 characters.
member
string
no
Omit for your own personal key; agent.<agent id> for an Agent key. Matches ^[a-z0-9._-]{1,64}$.
read_only
boolean
no
Narrow the key to read-only actions, for its whole life. Default false.
buckets
array of string
no
Narrow the key to these registered buckets of the account, for its whole life. Never with databases, database_prefixes, streams or stream_prefixes. At most 20 items. No duplicates.
databases
array of string
no
Narrow the key to these databases, for its whole life; a name need not exist yet. Never with buckets. At most 20 items. No duplicates.
database_prefixes
array of string
no
Narrow the key to the databases whose name starts with one of these, for its whole life. Never with buckets. At most 20 items. No duplicates.
streams
array of string
no
Narrow the key to these raw streams, by the name the streams API shows, for its whole life; a name need not exist yet. Never with buckets. A key narrowed to both databases and streams reaches both. At most 20 items. No duplicates.
stream_prefixes
array of string
no
Narrow the key to the raw streams whose name starts with one of these, for its whole life; each at most 83 bytes, the longest stream name. Never with buckets. At most 20 items. No duplicates.
expires_in
one of "15_days", "1_month", "6_months", "1_year" or "never"
no
How long the key lives from now; it never expires when omitted. Default "never".
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
The name is held by another live resource of the account, the Idempotency-Key already created another resource or one since deleted, or the resource’s current state does not allow the change. detail says which, and errors names the field.
No
Pick another name or a new Idempotency-Key, or read the resource again and act on its current state. (more)
The key or the account sent more requests than its rate allows.
After Retry-After
Wait for the seconds Retry-After names, then send the request again; spread requests out if it recurs. (more)
Retries
No Idempotency-Key: the secret is never stored, so a replay cannot return it; a live key name is unique, so a blind retry answers 409 instead of creating a second key.
429 carry Retry-After: wait that many seconds, then send the same request again.
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
The key’s role does not hold the capability the operation needs, the key is narrowed away from the resource, or the account already holds as many of the resource as it may.
No
Use a key whose role holds the capability, or one that is not narrowed; delete what you no longer need, or ask for a higher limit. (more)
The key's id, which GET and DELETE /v1/api-keys/{key_id} name.
name
string
yes
The key's name, unique, ignoring case, among its member's live keys.
member
string
yes
Who the key acts as, with that member's current role: a person's user id, or agent.<agent id> for an Agent key. Matches ^[a-z0-9._-]{1,64}$.
member_kind
one of "user" or "agent"
yes
user for a person's key, agent for an Agent key.
last4
string
yes
The secret's last four characters, to tell keys apart; the secret itself is shown only when the key is created. 4 to 4 characters.
read_only
boolean
yes
Whether the key is narrowed to read-only actions.
buckets
array of string
yes
The buckets the key is narrowed to; empty when it is not narrowed by bucket.
databases
array of string
yes
The database names the key is narrowed to. A key whose five narrowing lists are all empty reaches everything its member does; otherwise it reaches only what the lists name.
database_prefixes
array of string
yes
The database name prefixes the key is narrowed to.
streams
array of string
yes
The stream names the key is narrowed to, without s..
stream_prefixes
array of string
yes
The stream name prefixes the key is narrowed to.
expires_at
string (date-time) or null
yes
When the key stops working; null when it never expires.
The key's id, which GET and DELETE /v1/api-keys/{key_id} name.
name
string
yes
The key's name, unique, ignoring case, among its member's live keys.
member
string
yes
Who the key acts as, with that member's current role: a person's user id, or agent.<agent id> for an Agent key. Matches ^[a-z0-9._-]{1,64}$.
member_kind
one of "user" or "agent"
yes
user for a person's key, agent for an Agent key.
last4
string
yes
The secret's last four characters, to tell keys apart; the secret itself is shown only when the key is created. 4 to 4 characters.
read_only
boolean
yes
Whether the key is narrowed to read-only actions.
buckets
array of string
yes
The buckets the key is narrowed to; empty when it is not narrowed by bucket.
databases
array of string
yes
The database names the key is narrowed to. A key whose five narrowing lists are all empty reaches everything its member does; otherwise it reaches only what the lists name.
database_prefixes
array of string
yes
The database name prefixes the key is narrowed to.
streams
array of string
yes
The stream names the key is narrowed to, without s..
stream_prefixes
array of string
yes
The stream name prefixes the key is narrowed to.
expires_at
string (date-time) or null
yes
When the key stops working; null when it never expires.
last_used_at
string (date-time) or null
yes
Recorded at most once a minute.
created_at
string (date-time)
yes
When the key was created.
key
string
yes
The secret, shown once. tbo_ followed by 50 base-58 characters, the last six a checksum. Matches ^tbo_[1-9A-HJ-NP-Za-km-z]{50}$.