Organization API Keys
Organization API key management
List API keys
Create API key
Required Permissions:
apikey:write
Create API key
path Parameters
organization_idOrganization ID
Create API key › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object · requires: expiration_time, name, role_id |
Create API key › Responses
API key created successfully
created_atdescriptionexpiration_timeidjwt_signing_key_idJWTSigningKeyID is the jwt_signing_keys row that signed the key's current token. Re-stamped on rotation. Empty when signed via the legacy HS256 path (no signing-key row), or for keys created before this was recorded.
last_used_atLastUsedAt is when the key, or a token minted from it, last authenticated a request. Recorded at most once a minute, so it can lag real use by that much. Nil when the key has not been used since tracking began.
nameorganization_idprevious_token_expiration_timePreviousTokenExpirationTime is when the token of the previous generation (TokenVersion-1) stops being accepted. Nil means it was revoked on rotation. Returned as stored, so it may be in the past.
role_idtokentoken_versionTokenVersion is the current generation of the key. It is embedded in
minted JWTs as the ver claim and bumped on rotation to invalidate
previously-issued tokens without changing the key's id.
updated_atGet API key
Required Permissions:
apikey:read
Get API key
path Parameters
organization_idOrganization ID
api_key_idAPI Key ID
Get API key › Responses
API key details
created_atdescriptionexpiration_timeidjwt_signing_key_idJWTSigningKeyID is the jwt_signing_keys row that signed the key's current token. Re-stamped on rotation. Empty when signed via the legacy HS256 path (no signing-key row), or for keys created before this was recorded.
last_used_atLastUsedAt is when the key, or a token minted from it, last authenticated a request. Recorded at most once a minute, so it can lag real use by that much. Nil when the key has not been used since tracking began.
nameorganization_idprevious_token_expiration_timePreviousTokenExpirationTime is when the token of the previous generation (TokenVersion-1) stops being accepted. Nil means it was revoked on rotation. Returned as stored, so it may be in the past.
role_idtoken_versionTokenVersion is the current generation of the key. It is embedded in
minted JWTs as the ver claim and bumped on rotation to invalidate
previously-issued tokens without changing the key's id.
updated_atUpdate API key
Required Permissions:
apikey:write
Update API key
path Parameters
organization_idOrganization ID
api_key_idAPI Key ID
Update API key › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
Update API key › Responses
API key updated successfully
created_atdescriptionexpiration_timeidjwt_signing_key_idJWTSigningKeyID is the jwt_signing_keys row that signed the key's current token. Re-stamped on rotation. Empty when signed via the legacy HS256 path (no signing-key row), or for keys created before this was recorded.
last_used_atLastUsedAt is when the key, or a token minted from it, last authenticated a request. Recorded at most once a minute, so it can lag real use by that much. Nil when the key has not been used since tracking began.
nameorganization_idprevious_token_expiration_timePreviousTokenExpirationTime is when the token of the previous generation (TokenVersion-1) stops being accepted. Nil means it was revoked on rotation. Returned as stored, so it may be in the past.
role_idtoken_versionTokenVersion is the current generation of the key. It is embedded in
minted JWTs as the ver claim and bumped on rotation to invalidate
previously-issued tokens without changing the key's id.
updated_atRegenerate API key
Required Permissions:
apikey:write
Rotates an API key's secret in place, invalidating previously issued tokens. Keeps the existing expiration unless expiration_time is supplied; supplying one is required if the key has already expired. When previous_token_expiration_time is supplied, the previous token stays valid until then; omitted, it is revoked immediately. It must be at most 90 days ahead and not past the key's current or new expiration.
path Parameters
organization_idOrganization ID
api_key_idAPI Key ID
Regenerate API key › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object | |
| type = object |
Regenerate API key › Responses
New API key generated successfully
created_atdescriptionexpiration_timeidjwt_signing_key_idJWTSigningKeyID is the jwt_signing_keys row that signed the key's current token. Re-stamped on rotation. Empty when signed via the legacy HS256 path (no signing-key row), or for keys created before this was recorded.
last_used_atLastUsedAt is when the key, or a token minted from it, last authenticated a request. Recorded at most once a minute, so it can lag real use by that much. Nil when the key has not been used since tracking began.
nameorganization_idprevious_token_expiration_timePreviousTokenExpirationTime is when the token of the previous generation (TokenVersion-1) stops being accepted. Nil means it was revoked on rotation. Returned as stored, so it may be in the past.
role_idtokentoken_versionTokenVersion is the current generation of the key. It is embedded in
minted JWTs as the ver claim and bumped on rotation to invalidate
previously-issued tokens without changing the key's id.
updated_at