Skip to content

Operations: Admin API Tokens

Admin API tokens provide long-lived bearer authentication for automation.

Key behavior

  • Managed via /api/auth/api-tokens.
  • The UI is available to Superadmins at Settings > API tokens (/admin/api-tokens), not on the personal Profile page.
  • Token value is shown once at creation.
  • Revocation is immediate.
  • Expiration is enforced server-side.
  • Default lifetime is 30 days and the hard maximum is 90 days.
  • Listing and revocation require an active authorized interactive Admin session but do not require recent WebAuthn verification.
  • Creation requires recent WebAuthn verification when the global Admin passkey policy is enabled; otherwise the interactive Admin session is sufficient.
  • The JWT and database row must contain the same scopes and auth_version.
  • Browser UI cookies cannot be combined with a Bearer token.

Required scopes

Choose the minimum read and write scopes from profile, admin, manager, browser, portal, ceph-admin, and storage-ops. A token is denied on every protected route that has no explicit scope mapping.

Bearer tokens cannot call the direct UI-user and identity-security routes. No non-interactive identity-mutation endpoint is exposed; use an authorized browser-backed Admin session.

Runtime controls

  • API_TOKEN_DEFAULT_EXPIRE_DAYS
  • API_TOKEN_MAX_EXPIRE_DAYS
  • Create dedicated tokens per automation scope.
  • Store in secret manager.
  • Rotate regularly and revoke on decommission.
  • Recreate all API tokens after the authentication cutover migrations 0107–0110.