Authentication

Authorization: Bearer vsk_live_…

Keys are minted on 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. The examples in the API reference 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.

Get started

Concepts

Guides

Scopes

​Scopes

Scopes