Authentication

API keys, scopes, and how to authenticate requests against the public API.

Every request to /api/v1 carries an API key in the Authorization header.

Headers

Authorization: Bearer <api-key>
Content-Type: application/json   (on POST / PUT / PATCH)

Key format

Public API keys begin with obs_pub_ followed by a base64url opaque string. Keys are issued per organisation in the console under API keys. Each key is shown once at creation; the cloud stores its hash and cannot recover the plaintext.

Scopes

Each key carries a fixed set of scopes that gate which endpoints the key may call. The scopes available today:

Scope	Grants
`read:metrics`	Read metric definitions, current values, and aggregated history.
`write:metrics`	Set the status of manually-managed metrics.
`read:slos`	Read SLOs and their current burn state. (read-only)
`read:services`	Read service entities. (read-only)
`read:incidents`	Read incident updates published on status pages.
`write:incidents`	Create and update incidents.
`read:maintenances`	Read scheduled maintenance windows.
`write:maintenances`	Schedule, transition, and cancel maintenance windows.
`read:config`	Export the organisation's config-as-code document.
`write:config`	Apply a config-as-code document.
`read:change_events`	Read ingested deploy / release change events.
`write:change_events`	Ingest deploy / commit / release change events.

SLOs and services are read-only over the API: there is no write:slos or write:services scope.

Scopes are additive. Requests against an endpoint whose required scope is not on the key return 403.

Errors

The API returns RFC 7807 problem-detail responses. An auth failure looks like this:

{
  "type": "https://observer.example/problems/unauthenticated",
  "title": "unauthenticated",
  "status": 401,
  "detail": "missing bearer token"
}

A missing bearer token and an invalid or revoked key both return 401 with title: unauthenticated; detail distinguishes them. A valid key without the required scope returns 403 with title: forbidden, and detail names the scope that was missing.

Branch on title, never on detail. See Errors and status codes for the full list of status codes, their title tokens, and the rate-limit headers.

Per-endpoint scope requirements appear on each operation page in the sidebar.

Rotation

Keys can be rotated through the console. Existing keys remain valid until you revoke them; revoke when an incident or personnel change requires it.

Was this page helpful?