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

# Authentication

> API keys, scopes, and how requests are authorized

Every request to `/api/preview/*` is authenticated with a bearer API key.

```
Authorization: Bearer dr_live_<keyId>_<secret>
```

## Generating a key

Go to **Settings → Developers** in the dashboard. Name the key (so you can
tell multiple keys apart during rotation), choose its scopes, and generate
it. The full key is shown exactly once. DocuRise never stores or
displays the plaintext secret again; only the key id prefix (e.g.
`dr_live_ab12****`) is shown afterward, alongside its scopes, creation date,
and last-used date.

You can hold multiple active keys at once — generate a new one before
revoking an old one to rotate without downtime.

## Scopes

| Scope | Grants |
| - | - |
| `documents:write` | Create and update documents (`POST /api/preview/documents`, `PATCH /api/preview/documents/{id}`) |
| `documents:read` | Read documents (status, expiry, email protection settings), folders and courses |
| `analytics:read` | Read document analytics (views, unique visitors, leads, conversion) |
| `email:read` | Read email broadcasts and aggregate email insights |
| `automations:read` | Read automations, tags and groups (names and counts only) |
| `products:read` | Read your product catalog |
| `contacts:tag` | Create a tag; add or remove a manual tag on one contact |
| `segments:write` | Create groups |
| `instagram:write` | Create, edit, pause and resume Instagram DM rules (`POST`, `PATCH /api/preview/instagram/rules…`) |
| `instagram:read` | List and read Instagram DM rules (`GET /api/preview/instagram/rules…`) |

The read scopes (`documents:read`, `analytics:read`, `email:read`, `automations:read`,
`products:read`, `instagram:read`) only read. When you generate a key, the **Read only**
button selects exactly those. A scope listed here may belong to an endpoint that has not
shipped yet; the scope itself already exists so you can grant it ahead of time.

A key with a missing scope for the route it's calling gets a `403
INSUFFICIENT_SCOPE` error. [Errors](https://docurise.io/docs/errors.md) lists every error code and what
to do about it.

### Adding a scope to an existing key

A key keeps the scopes it was created with, so a scope added in a later release
is missing from older keys. If a call starts returning `403 INSUFFICIENT_SCOPE`
after a release, open **Settings → Developers**, choose **Edit scopes** on the
key and tick the scope. The key itself does not change, so you don't have to
rotate the secret. Revoked keys can't be edited.

Call `GET /api/preview/whoami` to see which scopes a key currently has.

## Plan requirement

Every route also requires a plan that includes API access, independent of
scopes. A key on a plan without it gets a `403 PLAN_REQUIRED` error even with
the right scope.

## Revoking a key

Revoke a key from the same Settings → Developers page. Revocation is
immediate and irreversible — the very next request using that key fails
authentication (`401 UNAUTHORIZED`). Revoked keys stay listed but can't be un-revoked; generate a new one instead.

## Preview access

During the API preview, the API is available to some accounts only. A key only
works on an account that has API access, independent of plan and scopes. An
account without it gets a `404` from every route If you expect access and get a `404`, check with
your DocuRise contact. Once an account has preview access, a plan without API
access gets a different error: `403 PLAN_REQUIRED`.


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