Skip to main content
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.

Keys and single sign-on

Single sign-on governs signing in to the dashboard, not API keys. A key belongs to your organisation, and a request made with one involves no sign-in, so turning single sign-on on or requiring it changes nothing for your integration. Removing a member does not revoke the keys they created, but from then on these requests made with one of those keys can be refused with api_key_owner_removed: Its other permissions stay until you revoke it. So before you remove somebody whose keys an integration uses, move the integration to a key created by somebody who is staying, on API keys in Settings; then revoke their keys. Removing somebody also affects envelopes sent in their name, which is not always whoever’s key sent them: Who the emails name says how, so deal with those first.

Scopes

What an API key may do. A key’s scopes are chosen when it is created, and an owner or admin can change them later under Settings → API keys (Edit permissions); the key itself does not change, and every change is recorded with who made it. There is no API endpoint that changes a key’s scopes. ⚠️ 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. ⚠️ A READ-ONLY KEY GROWS THE SAME WAY, BY READS ONLY. A key whose scopes are all read scopes from this list and include templates:read, envelopes:read, documents:read and webhooks:read (what every read-only key has held since the first) is treated as read-only: it holds every read scope there is, including each one added after it was created (so far authorisations:read and brands:read), and never a write or an explicit-only scope. Any other hand-picked list holds exactly the scopes it names. Each operation publishes the scope it requires as x-required-scope, and an operation that needs more than one lists the others in x-additional-required-scopes; a key that does not hold every one is refused insufficient_scope (403) with a WWW-Authenticate header naming the scopes, per RFC 6750 §3.1. A scope that a full-access key does not hold must be given to a key by name. You do not need a new key to gain one, or any other change of access: an owner or admin opens Edit permissions on the key under API keys in Settings. The key itself stays the same, so nothing using it needs updating, and the change applies from its next request. A read-only key holds every read scope, including ones added after it was created, such as authorisations:read and brands:read, and never gains a scope that writes. What counts as read-only is set out above: a list made only of read scopes that includes the original read-only set. Any other hand-picked list holds exactly the scopes it names.