> ## Documentation Index
> Fetch the complete documentation index at: https://docs.use.observer/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```text theme={null}
Authorization: Bearer <api-key>
Content-Type: application/json   (on POST / 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 **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:

| Scope | Grants |
| - | - |
| `read:metrics` | Read metric definitions, current values, aggregated history, and heartbeat state. |
| `write:metrics` | Set the status of manually-managed metrics, rotate heartbeat ping URLs, and run probe tests. Heartbeat reads made with this scope also include the ping URL. |
| `read:slos` | Read SLOs and their current burn state. (read-only) |
| `read:services` | Read service entities. (read-only) |
| `read:incidents` | Read incidents (drafts included), their updates, and internal notes. |
| `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, and list and read status pages. |
| `write:config` | Apply a config-as-code document, change status page settings, run probe tests, and delete config-managed metrics, services, SLOs and status pages one at a time. Heartbeat reads made with this scope also include the ping URL. |
| `read:agents` | List Observer Agents and read whether each is online. |
| `write:agents` | Create Observer Agents, issue new agent keys, and delete agents. |
| `read:change_events` | Reserved. Keys can carry it, but no endpoint requires it yet. |
| `write:change_events` | Ingest deploy / commit / release change events. |
| `read:sla` | Read SLA statements (plans with the SLA Ledger). |
| `read:audit` | Read and export the audit log (Business and Enterprise). |

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](https://docs.use.observer/docs/mcp/index.md) 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](https://docs.use.observer/docs/mcp/oauth.md).

## Errors

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

```json theme={null}
{
  "type": "https://docs.use.observer/api/getting-started/errors#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.
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](https://docs.use.observer/api/getting-started/errors.md) for the full
list of status codes and their `title` tokens, and
[Rate limits](https://docs.use.observer/api/getting-started/rate-limits.md) for the per-plan
limits and headers.

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

> [!NOTE]
>
> **Rotation**
>
> To 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.