Skip to main content

API Tokens

StatiBeat includes page-admin API token management for programmatic access to the StatusPage API.

API token management in the live demo

tip

Create tokens with the narrowest API scope and page role that still fit the job.

This guide is based on:

  • application/frontend/src/pages/admin/APITokenManagement.jsx
  • application/backend/cmd/server/routes.go
  • application/frontend/src/services/api.js

What the token screen supports​

The current token UI supports:

  • create token
  • list tokens
  • revoke token
  • delete token
  • inspect audit log
  • view token statistics

The stats cards currently track:

  • total
  • active
  • revoked
  • expired

Token fields​

When creating a token, the current form supports:

  • name
  • description
  • notes
  • permission
  • role_key via the RBAC Role selector
  • terraform_managed
  • expires_at

The frontend also filters out session tokens from the list so this view stays focused on actual API credentials.

API scope and page role​

The current UI exposes three API scope levels:

  • read
  • write
  • admin

The token form also requires an RBAC Role selection. In the current page-scoped admin surface:

  • permission is the API scope: read, write, or admin
  • RBAC Role controls which page-admin features the token can access inside the scoped workspace

That means final access is the intersection of both. Two tokens with the same API scope can still differ in what they are allowed to manage if they are assigned different page roles.

Role selection behavior​

The current role selector uses page roles from the RBAC catalog.

  • built-in page roles are always available
  • custom page roles are assignable when advanced RBAC is enabled
  • if the workspace is below advanced RBAC, existing custom-role tokens can still appear in the list, but new token creation falls back to built-in roles only

The token table also shows the resolved RBAC role next to the permission badge so admins can see both layers of access at a glance.

Token lifecycle​

A token in the current system can be:

  • active
  • revoked
  • expired

The UI distinguishes those states visually, and the backend exposes audit-log and validation endpoints for token management flows.

Revocation and deletion​

The current token management screen treats revocation and deletion as separate operations.

  • revocation asks for a reason
  • deletion is a permanent removal flow

That separation is useful because revocation preserves more operational context, while deletion is a stronger cleanup action.

warning

The token value itself is sensitive. The current UI includes a dedicated token-display modal because the raw token is something you should capture and store safely at creation time.

Terraform-managed tokens​

The token create flow includes a terraform_managed flag.

That lines up with the broader product emphasis on Terraform workflows. In the current admin UI, Terraform-managed tokens are the credentials expected to update features that have been locked for Terraform governance in customization settings.

That is a strong signal that you should document which tokens are intended for automation versus interactive use.

Practical guidance​

Good token practices in StatiBeat usually mean:

  1. set an expiration when possible
  2. use read for reporting and observation use cases
  3. use write only where automation truly needs mutation
  4. reserve admin for tightly controlled automation or platform administration
  5. revoke before delete when you want an audit trail of operational change

Automation token recommendations​

For page-level automation, think about token scope in three common buckets:

  1. Read-only automation Use read plus a page role that can see the resources you want scripts or reporting jobs to inspect.
  2. Workflow automation Use write plus the narrowest page role that can manage the incident, maintenance, or Beat actions the automation actually needs.
  3. Governance or provisioning automation Use admin only for tightly controlled automation that truly needs broader configuration access.

Practical defaults for automation tokens:

  • use a dedicated token per page and per integration or job
  • keep reporting and inspection workflows on read
  • only give write to workflows that truly need lifecycle actions
  • reserve admin for the small set of flows that genuinely need it
Why this matters for docs and automation

Once teams start using API tokens for Terraform, scripts, or integrations, those credentials become part of the operating model. Documenting token ownership, intended scope, and expiry policy makes incidents and offboarding much easier later.