Multi-Tenant Setup

This guide walks through embedding SignStack into a multi-tenant SaaS product: provisioning a namespace per end-customer, scoping API keys per tenant, distributing shared blueprints via the Library, and configuring per-tenant branding.

The full conceptual background is in Namespaces. This guide is the operational walkthrough.

The Mental Model

Every tenant in your product gets their own SignStack namespace. A namespace is a hard, system-enforced isolation boundary — resources, workflows, API keys, and branding all live inside one namespace and never cross over. Multi-tenancy in SignStack is just "one namespace per tenant."

Step 1: Provision a Namespace per Tenant

When a new tenant signs up in your product, your backend creates a SignStack namespace for them with per-tenant branding baked in:

curl -X POST https://api.signstack.ai/v1/orgs/{orgId}/namespaces \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "tenant-acme-corp",
    "name": "Acme Corp",
    "mode": "live",
    "settings": {
      "senderName":   "Acme Contracts",
      "senderEmail":  "contracts@acme.com",
      "company":      "Acme Corp",
      "contactEmail": "support@acme.com",
      "logoFileId":   "file_acme_logo_xyz"
    }
  }'

Use a stable, URL-safe key you can derive from your tenant ID (tenant-{slug} or tenant-{shortId}). Pick live for paid tenants, test for trials. See Namespaces for key/mode rules and the full BrandSettings field list.

Step 2: Mint a Per-Tenant API Key

Mint an API key inside the tenant's namespace so all their traffic stays scoped to it:

curl -X POST https://api.signstack.ai/v1/orgs/{orgId}/namespaces/tenant-acme-corp/api-keys \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp production key"
  }'

The returned key is shown once — store it in your secrets manager keyed by tenant. Your backend uses this tenant's key when making SignStack calls on their behalf.

Step 3: Distribute Shared Blueprints via the Library

If multiple tenants need the same blueprint — your domain-standard NDA, an industry-standard MSA, your starter contract pack — don't copy it into every namespace. Publish it once to the Library, org-scoped, with each tenant namespace granted access:

{
  "key": "standard_nda",
  "resourceKey": "standard_nda",
  "resourceVersion": "1.2.0",
  "resourceType": "blueprint",
  "title": "Standard NDA",
  "description": "Mutual NDA approved by legal.",
  "scope": "org",
  "accessGrants": [
    { "orgId": "{yourOrgId}", "namespaceKeys": "*" }
  ]
}

Tenants can Try the listing directly (no copy in their namespace) or Customize it into their namespace as a fork they can adapt.

When you ship a new version of the underlying blueprint, publish a new listing version. Existing tenants stay on what they pinned; they can move at their own pace.

Step 4: Manage the Tenant Lifecycle

• Onboarding — provision namespace + API key + (optionally) install starter listings via Customize.
• Suspension — revoke the tenant's API key. Existing workflows continue running, but no new API calls succeed.
• Offboarding — keep the namespace for audit/retention purposes; revoke all keys. Deleting tenant data is a separate concern (currently namespace deletion isn't exposed; coordinate via support if needed).

Common Patterns

• One org, many tenants — Most multi-tenant SaaS uses a single SignStack org and one namespace per end-customer. Cleanest model.
• Org per tenant — Larger / regulated tenants who want their own org-level isolation (separate billing, separate user admin) get their own SignStack org. Heavier setup but maximum isolation.
• Per-environment namespaces per tenant — Production tenants might want their own tenant-acme-staging and tenant-acme-prod namespaces. Spin up with the same flow.

Related

• Namespaces — Conceptual overview, including what namespaces are and aren't
• Library and Publishing to the Library — How shared blueprints distribute across tenant namespaces
• Embedding Components — The white-label embed story for in-product surfaces
• Embed SignStack into Your App — Practical wiring