Skip to main content
Every request to /api/preview/* is authenticated with a bearer API key.

​
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

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 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.