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

Headers

Key format

Public API keys begin with obs_pub_ followed by a base64url opaque string. Keys are issued per organisation in the console under Developers > 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: SLOs, services, and SLA statements have no write scope of their own (there is no write:slos, write:services, or write:sla). Services and SLOs are created and changed through config apply, which needs write:config. write:agents returns agent keys (obs_live_), which let a host send data for your organization. Grant it only to clients you trust with that. write:incidents also covers AI drafts of incident updates (which never publish) and internal incident notes. read:incidents also covers the measured impact and the signed evidence export. GET /me needs no scope: any valid key can call it to read its own scopes, the plan, quotas, and rate limits. Scopes are additive. Requests against an endpoint whose required scope is not on the key return 403.

MCP clients and OAuth

MCP clients can connect to the MCP server with OAuth instead of a key. Each OAuth approval is backed by an API key with the approved scopes, listed under API keys and revoked the same way. See Connect with OAuth.

Errors

The API returns RFC 7807 problem-detail responses. An auth failure looks like this:
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. A key whose organization’s plan does not include the public API returns 403 with title: plan_does_not_permit_api. Branch on title, never on detail. See Errors and status codes for the full list of status codes and their title tokens, and Rate limits for the per-plan limits and headers. Per-endpoint scope requirements appear on each operation page in the sidebar.
RotationTo rotate, create a new key, move clients to it, then revoke the old one. Existing keys remain valid until you revoke them; revoke when an incident or personnel change requires it.