API keys

Manage operator API keys used by backend services.

Endpoints

Create request

{
  "name": "backend-prod",
  "scopes": ["launch:write", "users:read", "markets:read", "trades:read"]
}

Create response

• token is returned once.
• The token has exactly three dot-separated parts: pma.<key-id>.<secret>.
• key_prefix contains pma. plus the first eight key-id characters for operator recognition; it is not an authentication credential.

{
  "item": {
    "id": 1,
    "name": "backend-prod",
    "key_id": "<opaque-key-id>",
    "key_prefix": "pma.<first-8-key-id-chars>",
    "scopes": ["launch:write", "users:read", "markets:read"],
    "last4": "abcd",
    "revoked_at": null,
    "created_at": "2026-06-18T00:00:00.000Z",
    "updated_at": "2026-06-18T00:00:00.000Z"
  },
  "token": "pma.<key-id>.<secret>"
}

List response fields

List returns { items: [...] }, including revoked keys, newest creation time first (then highest ID). It is not paginated and never returns raw tokens. Nullable usage metadata may not update on every request because activity recording is asynchronous.

• id
• name
• key_id
• key_prefix
• scopes
• last4
• last_used_at
• last_used_ip
• last_used_user_agent
• revoked_at
• created_at
• updated_at

Rules

• ["*"] grants full scope.
• Only a caller that already has * may create a key with *.
• A non-wildcard caller may assign only scopes it already has.
• API key scopes can include markets:write, wallet_adapter:read, and wallet_adapter:write.
• API key scopes cannot include staffs:read or staffs:write; staff management requires a staff session.
• Invalid scopes -> 400 INVALID_SCOPES
• Empty name -> 400 INVALID_NAME
• Unknown revoke target -> 404 NOT_FOUND
• Raw token must never be persisted outside secret storage.

API keys are not accepted by private market requests or support tickets, even when they have markets:write or *. Granting a scope does not override an endpoint's staff-session requirement.

Revocation returns { "ok": true, "id": 1 }. Revoked keys fail subsequent authentication; revoking an already-revoked owned key is permitted. Revocation is not logout: the logout route does not revoke API keys. For rotation, create a replacement, distribute its one-time token through server-side secret storage, then revoke the old key.

An API-key create request does not automatically add read scopes for write scopes (unlike staff scope assignment). Include each needed scope explicitly.