Everything you need to authenticate against the Signstack API.

Credential types

Four credential types are involved:

• Namespace API key (sk_ns_*) — a long-lived secret minted in Studio (or via POST /v1/orgs/{orgId}/namespaces/{namespaceKey}/api-keys). Format: sk_ns_<mode>_<keyId>_<secret>. Scoped to a single namespace; inherits the namespace's mode (live or test). Use for everything inside a namespace: workflows, resources, files, webhooks, signing.
• Org API key (sk_org_*) — a long-lived secret minted via POST /v1/orgs/{orgId}/api-keys. Format: sk_org_<keyId>_<secret>. Scoped to the organization, not a namespace; carries no mode. Use for org-level operations that don't belong to a single namespace: managing organization settings, billing, and managing org keys themselves. Cannot call namespace endpoints — attempts return 403.
• Access token — a short-lived JWT (1 hour) you obtain by exchanging an API key at POST /v1/auth/token. Send it as Authorization: Bearer <token> on every other request. Refresh proactively before expiry rather than reactively on 401.
• Embed token — a short-lived, intent-scoped JWT minted at POST .../auth/embed. Pass to a SignStack web component (<ss-signing-embed>, <ss-workflow-editor>, <ss-workflow-monitor>, <ss-resource-editor>). Safe to send to the browser; the long-lived API key and access token must never leave your backend.

For every API key, the full secret is shown only once at creation time and can never be retrieved later — store it immediately in your secret management system. To replace a lost secret, revoke the key and create a new one.

When to use which API key

You want to…	Credential
Run workflows, render templates, manage resources inside a namespace	Namespace key (sk_ns_*)
Sign documents, upload files, listen for webhooks	Namespace key (sk_ns_*)
Read/update the organization, invite users, manage billing	Org key (sk_org_*)
Mint or revoke org API keys	Org key (sk_org_*) with org-api-key:*

The prefix (sk_ns_* vs sk_org_*) is a load-bearing operational signal: audit tooling, log scrubbers, and rotation policies can distinguish the two credential classes at a glance.

Per-class scope allowlist

Namespace keys may carry any namespace-relevant scope (the full scope catalog).

Org keys may only carry these scopes — anything else returns 400 at mint time:

• organization:read, organization:update
• user:read, user:create, user:update
• org-api-key:read, org-api-key:create, org-api-key:delete
• billing:read, billing:manage

Namespace-related scopes (namespace:read / namespace:update) are deliberately not on the org-key allowlist — single-namespace metadata operations are fully covered by namespace keys (their URL is bound to a specific :namespaceKey).

The operations below cover all four credential types: minting and managing namespace + org API keys, exchanging keys for access tokens, and minting embed tokens for the browser.