# API keys and scopes

_Give code and AI clients exactly as much access as they need._

Canonical: https://snoze.dev/help/api-keys-and-scopes/

Everything that reaches your workspace from outside the app — a script, the
[MCP server](https://snoze.dev/help/set-up-the-mcp-server/), a CI job — authenticates with a
**workspace API key**. Keys are scoped, so each one can do exactly what you
grant it and nothing more.

## Create a key

1. **Open API keys**

   Go to workspace settings and open the **API keys** section.

2. **Name it and pick scopes**

   Name the key after what will hold it — "CI importer", "Claude MCP" — and
   grant only the scopes it needs. Scopes come in read/write pairs per area:
   a key can read databases without being able to change them, or run
   actions without touching anything else.

3. **Copy the token — once**

   The full token (`snoze_sk_…`) is shown a single time at creation. Store it
   in a secret manager; Snoze keeps only a hash, so it can't be shown again.

## Use it

Send the key as a bearer token on every request:

```bash
curl "https://api.snoze.dev/v1/items" \
  -H "Authorization: Bearer $SNOZE_API_KEY"
```

The same key works for the REST API and the MCP server. Requests beyond the
key's scopes fail with a `403` — the request that worked yesterday keeps
working tomorrow, and nothing silently escalates.

## Least privilege, in practice

- **Read-only for assistants** that only search and summarize — they can never
  modify or delete anything, no matter what they're asked.
- **One key per integration**, named for it — so revoking one doesn't break
  the others, and the request log tells you who did what.
- **Expiry dates for anything temporary** — a contractor's script shouldn't
  outlive the contract.

## Rotate and revoke

Revoking a key cuts its access immediately — in-flight tokens stop working on
the next request. To rotate, create the replacement first, move the
integration over, then revoke the old one. Every request made with a key is
logged with its status and timing, so you can verify the switch before
cutting over.

> [!WARNING]
> Treat keys like passwords: never commit them, never paste them into shared
> documents. If a key leaks, revoke it — creating a fresh one takes seconds.

For endpoint-by-endpoint details, request samples, and the full scope list,
see the [developer docs](https://developers.snoze.dev).