Namespaces

A namespace is an isolated environment inside your organization. Every resource in SignStack — schemas, templates, blueprints, assets, functions, scenarios, workflows, API keys, webhooks — belongs to exactly one namespace. Namespaces never share data directly. (When you do want controlled sharing across namespaces, that's what the Library is for.)

You'll see namespaceKey in every resource-scoped API path:

POST /v1/orgs/{orgId}/namespaces/{namespaceKey}/blueprints
GET  /v1/orgs/{orgId}/namespaces/{namespaceKey}/workflows

Multi-Tenancy

Namespaces let you scope agreement workflows per tenant in your product. If you're embedding SignStack into a SaaS, give each end-customer their own namespace — and you get a hard, system-enforced boundary between tenants for everything SignStack manages:

Resource isolation. A blueprint in tenant-acme is invisible to anyone authenticated against tenant-globex. There's no way to leak across.
API key scoping. API keys are minted inside a namespace and bound to it; the issued access token carries the namespaceKey claim, so every request a tenant makes is automatically constrained to their namespace.
Workflow separation. Workflows, signing audit trails, and event streams stay inside the originating namespace.
Independent branding. Each tenant gets their own sender identity, logo, and contact details (see below).

Isolation doesn't mean duplication. When the same blueprint or template applies across many tenants — a corporate-standard NDA, a shared starter contract — publish it once to the Library and grant access to your tenant namespaces. Each tenant can run the listing in the library directly, or fork it in their namespace to customize and adapt it from there.

Common patterns:

Use case	Strategy
Single-product SaaS, dev + prod	Use `default-test` and `ns-live`
Multi-tenant platform	One namespace per tenant (e.g., `tenant-{id}`)
Separate QA / staging	Add `qa-test` and `staging-live` namespaces
Per-team isolation	Namespace per team (e.g., `hr-live`, `sales-live`)

Custom Branding

Each namespace can carry its own brand settings — what your end-customer's signers see in emails, on the signing page, and on completed documents:

Field	Purpose
`senderName`	Display name on signing emails
`senderEmail`	"From" address on signing emails
`company`	Company name shown on signing pages
`contactEmail`	Reply-to / support address
`logoFileId`	Logo shown in emails and on signing pages
`phone`	Contact phone number
`address`	Mailing address

Per-namespace branding pairs naturally with Embedded Components — the namespace's brand drives every SignStack-managed touchpoint (emails, signing pages, completed documents), while embedded surfaces inside your app inherit your application's CSS for the in-product experience.

Test vs. Live Mode

Each namespace has a mode (test or live) set at creation:

Mode	Behavior
`test`	No billing for workflows. Ideal for development, CI, and demo environments.
`live`	Standard billing applies. Use for production workflows that send real signing requests.

Mode and key are immutable once a namespace exists; name and branding can be updated. API keys are bound to a namespace, which in turn determines whether workflow runs are billed.

Default Namespace

Every new organization is created with one default namespace:

Key	Mode	Purpose
`default-test`	`test`	Experimentation, local development, demos

You can create as many additional namespaces as you need — one per tenant, per team, per environment, etc.

Namespace Keys

Keys are URL-safe identifiers:

Lowercase letters, numbers, and hyphens
Must start with a letter and end with an alphanumeric character
3–50 characters
Cannot use reserved names (admin, api, system, internal, default, default-test, test, live, prod, production, staging, dev, development)

Valid: acme-prod, tenant-123, qa-sandbox Invalid: -acme, 123-tenant, tenant_1, TEST

API Keys and Namespaces

API keys are created inside a namespace. The key's scope is tied to that namespace, and the access token issued from POST /v1/auth/token carries the namespaceKey claim — so every request made with that token is automatically bound to the correct namespace.

This means:

You cannot reach a different namespace's data with a given token.
Test-mode and live-mode keys are distinct; mixing them is impossible by design.
Rotate keys per-namespace without affecting other namespaces.

Library — Controlled sharing of blueprints and templates across namespaces or with the public
A Full Guide to API Keys and JWTs
User-Level vs. Org-Level Authentication

File Management

Library