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 withapi_key_owner_removed:
POST /api/v1/templatesPATCH /api/v1/templates/{templateId}/fieldsPATCH /api/v1/templates/{templateId}/fields/{fieldId}POST /api/v1/templates/{templateId}/naming-runsPOST /api/v1/templates/{templateId}/naming-runs/{runId}/acceptPOST /api/v1/templates/{templateId}/naming-runs/{runId}/accept-currentPUT /api/v1/templates/{templateId}/people/{personId}POST /api/v1/templates/{templateId}/people/{personId}/accept-proposalPOST /api/v1/envelopesPOST /api/v1/envelopes/one-offPOST /api/v1/envelopes/batchesPOST /api/v1/envelopes/{envelopeId}/sendPOST /api/v1/standing-authorisations/{authorisationId}/renewPOST /api/v1/standing-authorisations/invitations
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 includetemplates: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.