API Reference

API Authentication

All API requests to Beacon require authentication via a workspace API token. This page covers token creation, usage, rate limits, and making your first authenticated request.

Creating API tokens

API tokens are created in the workspace settings:

Open the workspace dashboard.
Navigate to Settings, then API Tokens.
Click Create Token.
Give the token a descriptive name (e.g. "CI/CD Pipeline" or "Monitoring Service").
Click Create. The token is displayed once.

Important: Copy the token immediately and store it securely. Beacon does not store the plain-text token and cannot show it again. If you lose it, revoke the token and create a new one.

Token format

Beacon API tokens are prefixed strings that look like this:

bkn_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The bkn_live_ prefix makes tokens easy to identify in logs and secret scanners. Treat tokens like passwords -- never commit them to version control or expose them in client-side code.

Using tokens

Include the token in the Authorization header of every request using the Bearer scheme:

Authorization: Bearer bkn_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

All API requests must also include:

Content-Type: application/json — for requests with a body (POST, PATCH, PUT).
Accept: application/json — to receive JSON responses.

Base URL

All API endpoints are relative to:

https://usebeacon.pro/api/v1

For example, the full URL to create an incident on a page would be:

https://usebeacon.pro/api/v1/pages/acme-cloud/incidents

Rate limiting

Beacon enforces two levels of rate limiting to protect the platform:

Scope	Default limit	Window
Per workspace	120 requests	1 minute
Per IP address	60 requests	1 minute

Rate limit information is returned in response headers:

X-RateLimit-Limit — Maximum requests allowed in the window.
X-RateLimit-Remaining — Requests remaining in the current window.
Retry-After — Seconds until the rate limit resets (only present on 429 responses).

When you exceed the limit, Beacon returns 429 Too Many Requests. See the Errors & Rate Limits page for handling strategies.

Example: make a test call

Verify your token works by fetching a list of pages in your workspace:

curl -X GET https://usebeacon.pro/api/v1/pages \
  -H "Authorization: Bearer bkn_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Accept: application/json"

A successful response returns 200 OK with a JSON array of your status pages:

{
  "data": [
    {
      "id": "pg_1a2b3c4d5e6f",
      "name": "Acme Cloud",
      "slug": "acme-cloud",
      "is_public": true,
      "timezone": "America/New_York",
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-03-15T10:00:00Z"
    }
  ]
}

If you receive a 401 Unauthorized response, double-check that the token is correct and has not been revoked.