Scopes

Each API key is assigned one or more scopes that control which endpoints it can access.

Available scopes

Scope	Grants access to
envelopes:read	List envelopes, get envelope details, get status
envelopes:write	Create envelopes, upload paper PDFs, void, remind, update webhook config
esign:write	Mint sign-widget embed tokens
vault:read	Download vault documents, view certificates, mint vault embed tokens
vault:write	Trigger vault-in (vault a completed e-sign or paper upload)
vault:release	Vault-out — release the authoritative copy out of the live vault
customers:read	List and view customer records
compliance:read	View compliance evaluations and reports

Scope to endpoint mapping

Endpoint	Required scope
GET /partner/envelopes	envelopes:read
GET /partner/envelopes/:id	envelopes:read
GET /partner/envelopes/:id/status	envelopes:read
GET /partner/envelopes/:id/signing-links	envelopes:read
POST /partner/envelopes	envelopes:write
POST /partner/envelopes/:id/upload	envelopes:write
POST /partner/templates	envelopes:write
POST /partner/templates/:template_id/fields	envelopes:write
POST /partner/envelopes/:id/void	envelopes:write
POST /partner/envelopes/:id/remind	envelopes:write
PATCH /partner/webhook	envelopes:write
POST /embed/token (sign)	esign:write
POST /embed/token (vault)	vault:read
GET /partner/envelopes/:id/vault/signed-url	vault:read
GET /partner/envelopes/:id/vault/copy/signed-url	vault:read
POST /partner/envelopes/:id/vault-in-signed	vault:write
POST /partner/envelopes/:id/vault-in-upload	vault:write
POST /partner/envelopes/:id/vault-out	vault:release
GET /partner/envelopes/:id/vault/certificate	compliance:read
GET /partner/envelopes/:id/compliance	compliance:read

Recommended scope sets

Read-only integration

["envelopes:read", "vault:read", "compliance:read"]

Good for: dashboards, reporting, document viewing.

Full signing integration

["envelopes:read", "envelopes:write", "esign:write", "vault:read", "vault:write"]

Good for: end-to-end signing workflows where the partner triggers vault-in if needed.

Full e-sign + e-vault lifecycle

["envelopes:read", "envelopes:write", "vault:read", "vault:write", "vault:release", "compliance:read"]

Good for: integrations that drive the entire lifecycle including releasing the authoritative copy out of the vault to a secured party.

Complete access

["envelopes:read", "envelopes:write", "esign:write", "vault:read", "vault:write", "vault:release", "customers:read", "compliance:read"]

Good for: deep integrations that manage the full lifecycle including embedded widgets.

Notes on vault scopes

• vault:write is required for both signed and paper vault-in. The pipeline is the same end state — a vaulted envelope with a SHA-256 hash, UCC §9-105 compliance certificate, and vault custody record PDF. The difference is the source: a completed DocuSeal submission vs. a partner-uploaded PDF.
• vault:release is intentionally split from vault:write because vault-out is irreversible — the live authoritative path is deleted as part of UCC single-locus enforcement. Only grant this to keys that drive end-of-lifecycle release flows.

Error response

If a request requires a scope the key doesn't have:

// 403 Forbidden
{
  "error": "API key missing required scope: vault:release"
}