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

# Authentication

> Authenticate REST API requests with a server key

Every `/v1/*` endpoint requires a **server API key** (prefix `mir_srv_`). Keys are scoped to a single project — a request only ever sees data from the project its key belongs to.

## Server keys vs. SDK keys

Mirador uses different keys for different surfaces. Use the right one:

| Key            | Prefix     | Used for                                                             | Sent as                                 |
| -------------- | ---------- | -------------------------------------------------------------------- | --------------------------------------- |
| **Server key** | `mir_srv_` | The REST API (this section) — reading traces from a backend or agent | `Authorization: Bearer` or `X-API-Key`  |
| **Ingest key** | —          | The Web/Node SDKs — *writing* traces                                 | `x-ingest-api-key` (handled by the SDK) |

<Warning>
  Web keys are **rejected** by the REST API. If you get a `401` with
  `UNAUTHENTICATED`, confirm you're using a `mir_srv_*` server key and not an
  SDK/ingest or web key.
</Warning>

## Creating a server key

Create a server key in the Mirador dashboard under your **project's API keys**. Treat it like a password: it grants read access to every trace in that project.

## Sending the key

Pass the key on every request using **either** header:

<CodeGroup>
  ```bash Authorization: Bearer theme={null}
  curl -H "Authorization: Bearer $MIRADOR_SERVER_KEY" \
    https://api.mirador.org/v1/traces
  ```

  ```bash X-API-Key theme={null}
  curl -H "X-API-Key: $MIRADOR_SERVER_KEY" \
    https://api.mirador.org/v1/traces
  ```
</CodeGroup>

Verify a key resolves correctly before doing real work:

```bash theme={null}
curl -H "Authorization: Bearer $MIRADOR_SERVER_KEY" \
  https://api.mirador.org/v1/identity
# → { "organization_id": "org_...", "project_id": "prj_..." }
```

## Public endpoints

The documentation endpoints do **not** require a key:

* `GET /docs` — Swagger UI
* `GET /openapi.yaml`, `GET /openapi.json` — the OpenAPI contract
* `GET /llms.txt` — the agent-facing brief
* `GET /health` — liveness check

## Keeping keys safe

<Tip>
  * Store keys in environment variables or a secrets manager — never in source control.
  * Use a separate key per integration so you can rotate or revoke one without affecting others.
  * Scope keys to the project they need; a key cannot read across projects.
  * Rotate keys periodically and on staff changes.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Endpoints" icon="list" href="/api/endpoints">
    Every endpoint, filter, and response shape
  </Card>

  <Card title="Exporting traces" icon="file-export" href="/api/trace-export">
    Pull a full trace + events into another system
  </Card>
</CardGroup>