API Authentication

StatusRadar does not use a single authentication scheme. Different API surfaces use different credentials, because they are reached by different clients (your code, your servers, the browser). This guide documents all three schemes, where to get each token, and how to send it.

Authentication Schemes at a Glance

Sending the right credential to the right host matters: an OTLP app token will not authenticate against the User API, and a Bearer token is not accepted by the RUM collector.

The public endpoints GET /api/status/{slug} and GET /api/monitors/{id}/uptime require no authentication.

1. User API and Probe API — Authorization: Bearer <token>

The User API (manage monitors, incidents, status pages) and the Probe API (distributed check execution) both authenticate with a Bearer token in the Authorization header.

Authorization: Bearer YOUR_TOKEN

Where to get the token

• User API token — Dashboard → Settings → API (/dashboard/settings/api). Click Generate New Token, give it a name, and copy it. The token is shown only once; if lost, generate a new one. Revoke from the same page.
• Probe token — issued by StatusRadar when a probe server is provisioned. Probe tokens are managed by the platform, not self-served.

curl examples

List your monitors (User API):

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://api.statusradar.dev/v1/monitors

Create a monitor (User API):

curl -X POST https://api.statusradar.dev/v1/monitors \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Website","target":"https://example.com","type":"http"}'

Fetch pending checks (Probe API):

curl -H "Authorization: Bearer YOUR_PROBE_TOKEN" \
  https://api.statusradar.dev/v1/probe/get-checks

Submit a check result (Probe API):

curl -X POST https://api.statusradar.dev/v1/probe/check-result \
  -H "Authorization: Bearer YOUR_PROBE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"monitor_id":123,"status":"up","response_time_ms":142}'

The Probe API is also reachable on the main domain (statusradar.dev/v1/...). The api. subdomain is preferred for API clients.

2. OTLP Ingestion — X-App-Token: <token>

OpenTelemetry trace, log, and metric ingestion uses a per-application token sent in the X-App-Token header, against otlp.statusradar.dev. This is the credential your backend OTLP exporter (or the StatusRadar SDK / telemetry-agent) uses.

X-App-Token: YOUR_APP_TOKEN

Where to get the token

Dashboard → Observability (/dashboard/observability). Create or open an observability app; its app token is shown on the app's settings page (/dashboard/observability/{id}/settings). Each app has its own token plus an optional domain whitelist for CORS.

curl examples

Send traces:

curl -X POST https://otlp.statusradar.dev/v1/traces \
  -H "X-App-Token: YOUR_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d @traces.json

Send logs:

curl -X POST https://otlp.statusradar.dev/v1/logs \
  -H "X-App-Token: YOUR_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d @logs.json

Send metrics:

curl -X POST https://otlp.statusradar.dev/v1/metrics \
  -H "X-App-Token: YOUR_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d @metrics.json

See OTLP Overview and OTLP SDKs for exporter configuration.

3. RUM Ingestion — api_key query parameter

Real User Monitoring runs in the browser, so it cannot rely on a private header secret the way a backend can. The browser SDK posts events to rum.statusradar.dev/v1/ingest with the app's key passed as the api_key query parameter.

POST https://rum.statusradar.dev/v1/ingest?api_key=YOUR_RUM_KEY

In the browser SDK this is configured with the apiKey option; the SDK forwards it as the api_key query parameter on each request.

Where to get the key

Dashboard → Observability (/dashboard/observability). The same observability app exposes an api_key used by the RUM browser SDK. Because the RUM key is shipped to browsers, protect it with the app's domain whitelist (Origin/CORS allow-list) under the app's settings (/dashboard/observability/{id}/settings) rather than treating it as a secret.

curl example

curl -X POST "https://rum.statusradar.dev/v1/ingest?api_key=YOUR_RUM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"pageload","url":"https://example.com/","duration_ms":820}'

Browser SDK

StatusRadarRUM.init({
  apiKey: 'YOUR_RUM_KEY',
  endpoint: 'https://rum.statusradar.dev/v1/ingest'
});

See RUM Quickstart for full setup.

Token Security

• Never commit tokens to version control. Load them from environment variables or a secrets manager.
• Use the right token per surface. A User/Probe Bearer token, an OTLP app token, and a RUM api_key are not interchangeable.
• Keep backend tokens off the front end. User API, Probe, and OTLP tokens are secrets and must stay server-side. Only the RUM api_key is intended for the browser, and it relies on the domain whitelist for protection.
• Rotate and revoke. Regenerate User API tokens periodically and revoke any token that may have leaked. Observability app tokens/keys are managed per app in the dashboard.

# Load from environment, never hardcode
export STATUSRADAR_TOKEN="your-token"
curl -H "Authorization: Bearer $STATUSRADAR_TOKEN" \
  https://api.statusradar.dev/v1/monitors

Authentication Errors

A missing or invalid credential returns 401 Unauthorized:

{
  "error": true,
  "message": "Unauthorized",
  "code": "unauthorized",
  "status": 401
}

Common causes:

• Wrong scheme for the surface — e.g. sending Authorization: Bearer to OTLP (which expects X-App-Token) or to RUM (which expects api_key).
• Wrong host — sending a request to api.statusradar.dev when the endpoint lives at otlp.statusradar.dev or rum.statusradar.dev.
• Malformed Bearer header — missing the Bearer prefix or containing extra spaces.
• Revoked token — revoked tokens stop working immediately; generate a new one.

# Inspect what credential is actually being sent
curl -v -H "Authorization: Bearer $STATUSRADAR_TOKEN" \
  https://api.statusradar.dev/v1/monitors 2>&1 | grep -i 'authorization\|x-app-token'

Next Steps

• API Overview - API structure, base URL, and conventions
• OTLP Overview - Send traces, logs, and metrics with X-App-Token
• RUM Quickstart - Wire up the browser SDK with your api_key
• Creating Observability Apps - Get your OTLP token and RUM key
• Observability Domains - Lock the RUM key to your origins