Skip to main content

API Authentication

For most integrations, StatiBeat has two primary 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

Admin session endpoints used solely by the StatiBeat application are not part of the published customer API contracts.

4. Viewer-session authentication​

Private status pages use an HTTP-only viewer session cookie. The Public & Visitor contract documents the supported viewer status, password login, logout, and SSO-start operations.

Viewer sessions grant access only to the selected private page. They do not grant page-administration privileges.

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

6. Ingest-token authentication​

External event sources use a page-scoped ingest credential. Send it in the preferred header:

X-External-Event-Token: <ingest-token>

The ingestion endpoint also accepts the credential in its documented path form or as an Authorization bearer value. Ingest tokens can submit events only; they are not page-administration API tokens.

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 viewer sessions for visitors to private pages.
  • Use magic tokens for emailed management and delegated-access flows.
  • Use ingest tokens for configured external event sources.

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.
  • Treat viewer-session and ingest credentials as page-scoped secrets.
  • Do not expose bearer or magic tokens in query strings.