Skip to main content

API Authentication

For most customers, StatiBeat has two API modes:

  • anonymous public page reads on your page or custom domain
  • bearer-token admin automation on that same page or custom domain

1. Anonymous public reads​

Some page-host routes are intentionally public and do not need an API token.

Examples:

  • /api/v1/settings
  • /api/v1/incidents
  • /api/v1/maintenances
  • /api/v1/pages/public/current-host

Use these when you want public status data, not admin control.

2. Bearer token authentication​

Programmatic admin integrations should use an API token in the Authorization header.

Authorization: Bearer <token>

This is the right model for:

  • CI/CD automation
  • Terraform and scripted provisioning
  • operational integrations that create or update incidents

Point your automation at the page or custom domain you want to manage, then call /api/v1/context, /api/v1/admin/..., or /api/v1/org/... directly without needing numeric org or page IDs.

See API Tokens for token scopes and lifecycle guidance. If you want the shortest end-to-end setup, start with API Quickstart.

3. Session authentication​

The web app uses an authenticated session cookie for browser-based admin and management flows.

This is the right model when:

  • a user is signed in through the UI
  • requests are made from the browser
  • you are not building an external integration

4. Magic-token authentication​

Subscriber, custom-view, RSS-feed, and management-link flows can use a magic token carried in the X-Magic-Token header.

X-Magic-Token: <magic-token>

This is an advanced delegated-access pattern, not the main automation path. It is used for flows such as:

  • managing subscriber preferences
  • managing custom views
  • managing RSS feeds
  • opening a management link without a full signed-in admin session

Choosing the right auth mode​

  • Use anonymous public routes for public status data.
  • Use bearer tokens for supported customer automation.
  • Use session auth for interactive product usage.
  • Use magic tokens for emailed management and delegated-access flows.

Security guidance​

  • Prefer the narrowest API-token scope that works for the integration.
  • Rotate and expire bearer tokens where possible.
  • Treat magic tokens as short-lived delegated credentials.
  • Do not expose bearer or magic tokens in query strings.