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

# Authentication

> One auth method per surface, enforced at the boundary.

Atlas exposes one URL prefix per audience, and **each prefix has exactly one
authentication method**, enforced in middleware. A handler never decides its own
auth, and credentials never cross surfaces.

| Prefix                 | Audience                         | Auth                |
| ---------------------- | -------------------------------- | ------------------- |
| `/api/v1/*`            | External developers (REST)       | API key             |
| `mcp.atlaswork.ai/mcp` | AI agents (Streamable HTTP MCP)  | OAuth 2.1           |
| `/api/signer/*`        | Document recipients (no account) | HMAC envelope token |
| `/api/auth/*`          | The Atlas web app (sessions)     | Better Auth         |
| `/api/health`          | Liveness probes                  | None                |
| `/api/openapi.json`    | Docs tooling                     | None                |

## API keys

API keys authenticate the REST API (`/api/v1`). Hosted MCP clients authenticate
through Atlas OAuth and never receive an API key.
Create and revoke them from the [dashboard](https://web-atlaswork.vercel.app);
each key is shown in full exactly once, at creation.

Pass the key as a bearer token:

```bash theme={null}
curl https://api-atlaswork.vercel.app/api/v1/ping \
  -H "Authorization: Bearer $ATLAS_API_KEY"
```

The `x-api-key` header is also accepted:

```bash theme={null}
curl https://api-atlaswork.vercel.app/api/v1/ping \
  -H "x-api-key: $ATLAS_API_KEY"
```

<Warning>
  Treat API keys as secrets. They are server-side credentials — never ship them in client-side code
  or commit them to source control. Each key is rate-limited and carries per-key usage visibility
  (last used) in the dashboard.
</Warning>

## Signer tokens

Recipients sign without ever creating an account. Each signing link carries a
stateless, HMAC-signed envelope token scoped to a single envelope (and
optionally a single signer, with an expiry). A valid signature proves Atlas
minted the token.

You never construct signer tokens yourself — Atlas issues them in the emailed
links. The `/api/signer/*` surface accepts the token as a bearer token or a
`token` query parameter, and is the only surface with CORS enabled (limited to
the apex web origin).

<Note>
  Least-privilege links: every emailed link authorizes exactly one person to do exactly one thing on
  exactly one envelope. A signer's link can never expose another participant's fields or a different
  envelope.
</Note>

## Errors

Authentication failures use the standard error envelope (see
[Errors](/guides/errors)):

```json theme={null}
{ "code": "unauthorized", "message": "Missing or invalid API key" }
```