Core Concepts

Embedding Components

SignStack ships its main Studio surfaces as embeddable web components. Drop them into your own application for a fully white-labeled experience — your users never leave your product, and every touchpoint carries your brand.

What You Can Embed

Three components, registered as framework-agnostic custom elements:

Component Tag Embed intent Purpose
Builder <signstack-builder> builder Author or edit a blueprint, template, asset, schema, or function inside your app
Workflow <signstack-workflow> workflow Edit a pending workflow or monitor an in-flight one — the component picks which view to render from the token's claims; no mode attribute needed
Participant <signstack-participant> participant Embed the e-signing flow for a participant in a workflow

All three work in React, Vue, Svelte, Angular, plain HTML, or anything else that speaks the DOM. They inherit your app's CSS — typography, colors, button styles — so the surfaces pick up your design system automatically.

The participant signing component is sandboxed for security: the actual signature capture runs in an isolated context to keep the signing UX separated from the rest of your app's DOM.

How They're Configured

Every component takes a single config attribute:

Attribute Purpose
embed-token Short-lived embed token issued by your backend. Carries the org, namespace, intent, and target (e.g. workflow ID) baked in as claims — the component reads them automatically.

That's the whole config surface. Components emit events you can listen to from your app (signed, declined, signingError, sessionExpired, closed, etc.) so you can react to lifecycle moments without polling. Event names are camelCase — they map verbatim to the component's outputs.

Authentication Model

Embed components don't use API keys directly. The flow is:

  1. Your backend (server-side) calls POST /v1/orgs/{orgId}/namespaces/{namespaceKey}/auth/embed with an API key, requesting an embed token for a specific intent — e.g. signing for participant X on workflow Y, or editing resource Z. The intent + target (workflow ID, resource key, etc.) get baked into the token.
  2. SignStack returns a short-lived JWT scoped to that intent.
  3. You pass that JWT to the web component as embed-token. Nothing else — no org ID, no namespace key, no target ID. They're all claims inside the token, extracted server-side at mint time and read by the component on the client.
  4. The component uses the token for all its API calls. When it expires, the participant component fires a sessionExpired event so your app can refresh.

This keeps the long-lived API key on your server, gives the browser only the permissions it needs for one embed session, and lets you revoke or expire access without touching the API key.

The full intent catalog (signing, workflow editing, resource editing, etc.) and token mechanics are covered in Securely Embedding Components.

Branding

Embedded components pick up branding from two sources:

  • Your app's CSS — flows through naturally. No theme override or token overrides needed.
  • The active namespace's brand settings — drive any SignStack-managed surfaces around the embed (signing emails, the signing page chrome, the completed document), so what your end-customer's signers see carries the right identity. See Namespaces — Custom Branding.

The combination means: in-product UI matches your design system; out-of-product touchpoints match the namespace's brand. Multi-tenant products get this per-tenant for free.

Choosing a Component

Use case Component
Let your users author or edit a blueprint, template, or schema <signstack-builder>
Edit a pending workflow or monitor an in-flight one <signstack-workflow>
Have a participant sign a document inside your app <signstack-participant>

<signstack-workflow> is one component covering both editor and monitor surfaces. The token's scopes are adapted to the calling API key (read-only vs update-capable); the workflow's live status is fetched by the component on mount and combined with those scopes to decide what to render:

  • pending workflow + API key holds workflow:update → editor view, with edit permission
  • pending workflow + read-only API key → monitor view (read-only)
  • in-flight workflow + API key holds workflow:update → monitor view with inline operator actions (reminders, cancel)
  • in-flight workflow + read-only API key → monitor view, read-only

Status is fetched live (one extra request on mount) rather than stamped into the token, so a workflow transitioning between mint and mount renders the right view. The capability is fixed at mint time — that one's a property of the API key.

Related

Previous
Library
Next
Generating Contracts with AI