API keys

Self-service management of the caller's own API keys

List the caller's API keys

Lists every API key owned by the calling principal, including revoked and expired keys. The secret token is never returned here — only metadata such as the name, last four characters, scopes, and status. A super-user key may inspect another owner's keys by passing owner_type and owner_id; for everyone else those parameters are ignored and only the caller's own keys are returned.

Create an API key owned by the caller (token shown once)

Mints a new key owned by the calling principal — the owner is always the caller and cannot be specified. The plaintext token is included in this response and only this response, so store it immediately; it cannot be retrieved later. Each requested scope must be a network/role the caller already holds (a key can only delegate a subset of its own access), and only a super-user key may set super_user=true. A key must request either super_user=true or at least one scope.

Get one of the caller's API keys

Returns metadata for a single key the caller owns; the secret token is never returned. A super-user may fetch any key. To avoid leaking whether an id exists, a key owned by someone else is reported as not found (404) rather than forbidden.

Revoke one of the caller's API keys

Soft-revokes a key the caller owns (a super-user may revoke any key): the key is marked revoked and stops authenticating immediately, but its record is kept rather than deleted. Revoking an already-revoked or expired key is a no-op and still returns success.