API keys

API keys are org-scoped credentials for server-to-server callers. One key, one org. To access multiple orgs from automation, mint a separate key for each. Revoking a key invalidates it immediately for all in-flight requests. Existing access tokens are unaffected (different auth path).

Endpoints

POST /auth/api-keys: mint a new key. Returns the secret once.
GET /auth/api-keys: list keys for the current org (no secrets).
PATCH /auth/api-keys/{id}: replace a key's IP allow-list.
DELETE /auth/api-keys/{id}: revoke a key.

All are callable with either auth scheme: Api-Key: or Authorization: Bearer. The bootstrap path is dashboard-login → mint, but anything is reachable once you have a key.

Permissions: any org member can mint a key or list the org's keys. Editing a key's allow-list and revoking it are both gated the same way: owner/admin can manage any key, everyone else can only manage keys they minted themselves. The list response carries a per-row can_revoke boolean so dashboards can render the right affordance without guessing.

Access levels

Each key carries an access level, chosen when the key is minted and fixed for its lifetime. To change a key's access, mint a new key and revoke the old one. A key never does more than its minting user's org role allows; access only narrows that.

`access`	What the key may do
`full`	Every request the minting user's role allows. The default when `access` is omitted.
`no_money_movement`	Everything except moving money and anything that could widen the key's own reach. Refused: accepting a quote, turning an account's auto-liquidation on or off, the sandbox deposit and funding simulations, org settings and members, webhook configuration, and API-key management. Allowed: creating quotes, cancelling orders, and managing customers, their verification and their accounts.
`read_only`	`GET` requests only. Every create, update or delete is refused.

A request the key's access withholds gets 403 ApiKeyAccessDenied, with the key's level in access:

{
  "ok": false,
  "error": {
    "code": "ApiKeyAccessDenied",
    "access": "read_only",
    "message": "this API key's access level does not permit this request"
  },
  "request_id": "req_3f2a9c0d1b7e4f6a8c5d2e1b0a9f8e7d"
}

Dashboard sessions (Authorization: Bearer) are not affected by key access levels.

IP allow-listing

Each key carries an ip_allowlist: a list of CIDR ranges and/or bare IP addresses the key may be used from. An empty list (the default) means no restriction: the key works from anywhere. A non-empty list restricts the key to callers whose address falls inside one of the entries. Any other caller gets 403 ApiKeyIpNotAllowed.

Both IPv4 and IPv6 are supported. A bare address (203.0.113.4) is treated as a single host. A range is written in CIDR notation (10.0.0.0/8, 2001:db8::/32).
Set it at mint time, or change it later with PATCH /auth/api-keys/{id}. Up to 50 entries per key.
The address Seismic evaluates is the connecting client's public IP as seen at our edge. Callers behind a proxy or NAT should allow-list the egress address their traffic actually leaves from.

Types

`ApiKey`

The shape returned from list + revoke responses, and the non-secret half of the mint response.

Field	Type	Notes
`id`	string (UUID)	Our id for the key.
`org_id`	string (UUID)
`prefix`	string	Public, non-sensitive prefix, e.g. `seismic_prod_abc12…`. Use to identify a key in logs / UI.
`created_by`	string (UUID)	User id of the minting user.
`created_at`	string (ISO-8601)
`expires_at`	string (ISO-8601)	When the key stops authenticating, even if not revoked. Server-set. Mint API doesn't accept a custom value.
`last_used_at`	string (ISO-8601) \| null	Updated lazily on each authenticated request.
`revoked_at`	string (ISO-8601) \| null	Set on revoke. Revoked keys still appear in list.
`ip_allowlist`	string[]	CIDR ranges / bare IPs the key may be used from. Empty ⇒ unrestricted. See IP allow-listing.
`access`	string	`full`, `no_money_movement` or `read_only`. Fixed at mint. See Access levels.
`can_revoke`	boolean	True if the calling user can revoke this key (`owner`/`admin` for any key; everyone else only for keys they minted). Computed per-caller, not a property of the key.

`ApiKeyMinted`

Returned only by POST /auth/api-keys. Extends ApiKey with the plaintext secret.

Field	Type	Notes
all of `ApiKey`
`secret`	string	Full plaintext key, `seismic_prod_…`. Surfaced once. We hash and discard server-side. Treat like a password.