Skip to main content

API Tokens

API tokens let scripts, integrations, and automation access the StatiBeat API for a specific page.

API Token Management with plan usage, token summary, and Create API Token action
API Token Management with plan usage, token summary, and Create API Token actionOpen full-size image
tip

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

What tokens are for​

Use API tokens for:

  • internal scripts
  • reporting jobs
  • Terraform workflows
  • monitoring or support tools
  • controlled incident, maintenance, or Beat automation

Do not use personal session credentials for automation. Create a dedicated token with a clear owner and purpose.

Create a token​

When creating a token, provide:

  • name
  • description or notes
  • API scope
  • page role
  • optional expiration
  • whether the token is Terraform-managed

The raw token value is shown only when it is created. Store it somewhere secure before closing the display.

API scope and page role​

Token access is controlled by two layers:

  • API scope: read, write, or admin
  • page role: the page-level permissions assigned to the token

Final access is the intersection of both layers. A write token still cannot manage a feature if its page role does not allow that feature.

Token lifecycle​

Tokens can be:

  • active
  • revoked
  • expired

Revocation and deletion are separate actions. Revoke a token when you want to stop access while preserving operational context. Delete only when you are intentionally cleaning up the credential record.

Terraform-managed tokens​

Use Terraform-managed tokens for configuration-as-code workflows.

Document which token belongs to which Terraform workspace or automation job. That makes rotation, offboarding, and incident response much easier later.

Practical guidance​

  1. Use one token per page and per integration.
  2. Set an expiration when possible.
  3. Use read for reporting and observation.
  4. Use write only for workflows that need to mutate incidents, maintenance, Beats, or similar resources.
  5. Reserve admin for tightly controlled provisioning or governance automation.
  6. Revoke tokens that are no longer owned or understood.