/api/v1 carries an API key in the
Authorization header.
Headers
Key format
Public API keys begin withobs_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: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.

