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

# Authentication

> One bearer header, and the scopes a key is minted with.

```text theme={null}
Authorization: Bearer vsk_live_…
```

Keys are minted on [API keys](https://app.vumasign.com/settings/api-keys) in Settings. `vsk_live_`
and `vsk_test_` are different keys: the environment is inside the hashed value, so a test secret
cannot be re-presented under a live prefix. What each can do is on
[Test keys and live keys](/concepts/test-and-live).

The examples in the [API reference](/api-reference/list-templates) send the key as a bearer token.
Put yours where each example's placeholder is, or into the playground's authorization field to send
the request from the page.

## Scopes

What an API key may do. A key’s scopes are chosen when it is minted and are immutable afterwards — there is no endpoint and no screen that can widen a key, by design, so a key that needs more access is replaced rather than edited. ⚠️ A key with NO scopes holds EVERY capability, not none: keys issued before scopes existed carry an empty list and are full keys, and nothing narrows them retroactively. Each operation publishes the one scope it requires as `x-required-scope`; a key that does not hold it is refused `insufficient_scope` (403) with a `WWW-Authenticate` header naming the scope, per RFC 6750 §3.1.

| Scope | What it allows |
| - | - |
| `templates:read` | Read templates: the list, one template’s documents, roles, subjects, questions and fields, and the geometry of every field on it. |
| `templates:write` | Author a template from an uploaded PDF. Field extraction runs on it, and what it produces is what every envelope made from it will ask for. |
| `envelopes:read` | Read one envelope: its status, its recipients and their delivery state. |
| `envelopes:write` | Create envelopes from a template, singly or in a batch, send them, and mint embedded signing URLs for their recipients. ⚠️ This is the scope that emails real people and spends billing allowance on a live key. |
| `documents:read` | Read a document’s bytes: the pages of a document belonging to a template this key can already see, as PDF; and, separately, the executed contract of any envelope this key’s organisation owns — original or sealed — via `GET .../envelopes/{envelopeId}/documents`. ⚠️ NARROWER THAN `envelopes:read` on purpose: a key that may read an envelope’s status is not thereby a key that may fetch what it holds. |
| `webhooks:read` | Read the registered webhook endpoints. Never their signing secrets. |
| `webhooks:write` | Register, change, rotate the secret of and delete webhook endpoints. ⚠️ An endpoint is where envelope events — carrying recipient names and addresses — are POSTed, so this scope decides where a copy of them goes. |