Signstack API

Overview

The Signstack API is the canonical surface for managing primitives (blueprints, templates, schemas, assets, functions), running workflows, and minting tokens for embedded UI. Every endpoint is REST + JSON; auth is JWT Bearer; and the resources you create here are the same ones you author in Studio or push from the CLI.

Studio and the CLI are themselves API clients. They call these same endpoints for the flows you'd integrate against — managing primitives, running workflows, minting tokens, configuring webhooks. Anything created via the API is immediately editable in Studio or via the CLI, and vice versa. Pick the interface that fits each part of your workflow.

Base URL

https://api.signstack.ai

All paths in this reference are relative to this host.

Authentication at a Glance

Every request (except POST /v1/auth/token) requires an Authorization: Bearer <accessToken> header. To get a token:

1. Mint an API key in Studio (Settings → API Keys).
2. Exchange it at POST /v1/auth/token for a 1-hour access token.
3. Send the access token as Authorization: Bearer <accessToken> on every other request.

For embedded UI, mint a separate embed token at POST .../auth/embed and pass it to a SignStack web component. The full credential model and operation reference live in the Authentication section below.

Namespace-Scoped URLs

Most endpoints are scoped to a namespace inside an organization:

/v1/orgs/{orgId}/namespaces/{namespaceKey}/<resource>

A namespace is the isolation boundary for primitives, workflows, branding, and API keys — give every tenant its own. A namespace is either live or test (its mode); API keys inherit the mode, so a test-mode key can never touch live-mode data. The orgId and namespaceKey for your token are returned in the token-exchange response.

The few non-namespaced endpoints are: POST /v1/auth/token, the user/organization endpoints under /v1/users and /v1/organizations, and the org-scoped file primitives under /v1/orgs/{orgId}/files/....

API Versioning

Paths are prefixed with /v1/. We add fields and endpoints within v1 without breaking changes. Breaking changes ship under a new major (/v2/...) with a deprecation window.

Resources you create carry their own semantic version (e.g. blueprint@1.2.0); resource versions are independent of the API version. Published resource versions are immutable — to change a published resource, edit the draft and publish again to emit a new version.

Errors

Failures use standard HTTP status codes (400, 401, 403, 404, 409, 429, 5xx). The body is always:

{
  "statusCode": 400,
  "timestamp": "2026-04-21T...Z",
  "path": "/v1/orgs/.../workflows",
  "traceId": "c0f8e2d1-...",
  "errorInfo": { "message": "..." }
}

There is no machine-readable error.code — branch on HTTP status; read errorInfo.message for human-readable detail. Mutating endpoints use the standard HTTP ETag / If-Match round-trip for optimistic locking: read responses return an ETag header, send it back as If-Match on the corresponding mutation, and a stale value returns 409. Full reference and recommended retry patterns are in the Error Handling guide.

Scopes

Each API key carries a fixed set of scopes chosen at creation time; the access token derived from it inherits them. Required scopes for each operation are listed in its x-required-scopes field. A 403 means the token's scopes don't cover the operation — mint a new key with the needed scopes (existing keys can't have scopes added or removed).

Full catalog and recommended scope sets for common integration patterns: Scopes reference.

Other Ways to Use SignStack

The API is one of four surfaces. The other three:

Visual UI:

• Studio — the SignStack web app. Visual workspace for authoring primitives, designing workflows, previewing, publishing, and running. Same operations as this API reference, in a UI.
• Embeddable web components — the same Studio surfaces extracted as drop-in custom elements (<ss-signing-embed>, <ss-workflow-editor>, <ss-workflow-monitor>, <ss-resource-editor>). Mount them inside your own product so signing, authoring, editing, and monitoring all happen under your brand — for external customers and internal teams alike. SignStack runs underneath. See Embed SignStack into Your App.

Developer tooling:

• CLI (signstack) — author, validate, preview, push, and run primitives from your repo. Built for the inner dev loop (edit → preview → iterate) and CI/CD pipelines alike. See Add SignStack to Your CI/CD Pipeline.

Where to Start

• New here? Walk through the Quick Start.
• Need the mental model? Read the Core Concepts.
• Implementing? Start with the Authentication section below to mint your first token.