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

• 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.