# eSignStack for Platforms

Give each of your customers their own eSignStack workspace, created, branded and run by your server through the API.

This guide is for software platforms that add e-signatures for their customers. It covers the flows in the order you build them. Request and response schemas are in the [API reference](/docs/api).

## How it fits together

| Concept            | What it is                                                                                                                         |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Platform           | Your organization's account. It owns customer workspaces, platform keys, platform webhooks, brand defaults and the console.        |
| Customer workspace | One customer's isolated space: templates, envelopes, branding, members. ID `ws_…`, plus your own `external_id`.                    |
| Platform key       | `sk_live_…` or `sk_test_…`. Acts on any of your workspaces when you send `Workspace-Id: ws_…`; without it, on platform endpoints.   |
| Workspace key      | `rk_live_…` or `rk_test_…`. Bound to one workspace, with an explicit list of abilities. Use one per customer to limit exposure.     |
| Platform member    | A person on your team who uses the [platform console](/docs/platform-console): an admin, developer, billing or support member.     |

Keys belong on your server. Never put one in a browser or mobile app; the browser only ever opens a short-lived session URL.

## Get set up

1. [Talk to us](/support) about your platform. We agree a Platform plan for the account that will pay for it.
2. We create your platform, link it to that paying account and make you its first admin.
3. Open **Platform console** from the workspace switcher or your user menu, invite your team, and create your first platform key.

### Billing

The Platform plan has no public price. We agree it with you, and it includes 25 customer workspaces.

- **In-app signing** in your customer workspaces is unlimited under fair use (normal use by your customers' own organizations).
- **API and MCP envelopes** from all of your workspaces count toward the paying account's allowance, which is part of your plan. When they and any envelope packs run out, API sends are refused with `api_envelope_limit_reached` until the allowance resets.
- An envelope counts once: when it's sent through the API or MCP, or when the API first creates a signing session for an envelope sent in the app. Sandbox envelopes never count.
- **Envelope packs:** on the paying account's **Billing** page, **Buy** adds a pack right away; pack envelopes carry over and last 12 months. Turn on **Buy automatically** so the send that finds nothing left buys a pack itself, up to the number of times a month you choose. See [Envelope packs](/docs/plans-and-billing#envelope-packs).

- **Customer workspaces:** a platform can have 25. Past that, creating one returns `403 permission_denied`; contact us to raise the limit.

Customer workspaces get the Platform plan's features, including custom branding, kiosk mode and signer verification. The console's **Settings** page shows who is billed and this period's API usage.

## 1. Create a workspace for each customer

Create a workspace when a customer signs up. Use your own customer ID as `external_id`: it's unique within your platform, so sending the same request again returns the same workspace (`201` the first time, `200` after). The same `external_id` with different attributes returns `409`.

```bash
curl -X POST "https://esignstack.app/api/v1/workspaces" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Idempotency-Key: customer-1001-create" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Dental",
    "external_id": "customer_1001",
    "metadata": { "region": "west" },
    "settings": {
      "embed_allowed_origins": ["https://acme.example.com"],
      "signing_return_allowed_origins": ["https://acme.example.com"],
      "default_signing_window_days": 14
    },
    "notification_policy": { "signing_request": "host", "reminder": "host" }
  }'
```

- Don't send `Workspace-Id` to the `/workspaces` endpoints. Store the returned `id` (`ws_…`) next to your customer.
- Creating, suspending and resuming workspaces needs a live key (`403 live_key_required`). Test and live keys list the same workspaces. With a test key, this list may in future also include test-only workspaces (`livemode: false`).
- Every workspace has a [sandbox](/docs/sandbox). A platform test key (`sk_test_`) with the workspace's `Workspace-Id` works in its sandbox, which is made on first use. Responses still name the workspace's `ws_…` ID, with `livemode: false`. Test envelopes are watermarked and never billed.
- The sandbox starts with a copy of the workspace's `settings` and `notification_policy`, then keeps its own. Branding always reads from the live workspace and needs a live key to change. Change them with a test key and `PATCH /workspaces/{workspace}`, for example to add the origins your test environment embeds signing from; live doesn't change. `GET /workspaces/{workspace}` with a test key shows the sandbox's values, with `livemode: false`. `name` and `metadata` are the same on both sides: a test key sending them gets `403 live_key_required` with `param` naming the attribute.
- `settings` accepts `embed_allowed_origins` and `signing_return_allowed_origins` (origins only: no path, query or credentials; up to 50 return origins), `default_signing_window_days` (1–365), the signing disclosure text (`esign_disclosure_title`, `esign_disclosure_body`, `esign_disclosure_agreement_label`) (`null` uses the default) and `require_esign_consent` (whether signers must agree to the disclosure before signing). A workspace's `settings` reads the same on `GET /workspaces/{workspace}` and on `GET /workspace` with the workspace's own key, which can change the defaults (`PATCH /workspace`) but not the origins or disclosure wording.
- `notification_policy` says who sends each email: `esignstack` (we send it) or `host` (we stay silent; you notify people yourself). `PATCH` changes only the kinds you send; null for a kind goes back to `esignstack`. Kinds: `signing_request`, `reminder`, `sequential_handoff`, `completed_copy_recipients`, `completed_copy_cc`, `owner_completed`, `delivery_problem`, `declined`, `voided`.
- `metadata` takes up to 20 string key/value pairs. Don't store secrets there.
- `brand_kit` takes an object of kit fields, or `null` to delete the workspace’s own kit and use platform defaults (see Branding below).

Other workspace calls:

| Task                          | Request                                                                                  |
| ----------------------------- | ---------------------------------------------------------------------------------------- |
| Find a customer's workspace   | `GET /workspaces?filter[external_id]=customer_1001` (also `filter[status]`, `filter[name]`) |
| Update                        | `PATCH /workspaces/{workspace}` (`external_id` can't change; a test key changes the sandbox's settings) |
| Suspend or resume             | `POST /workspaces/{workspace}/suspend`, `POST /workspaces/{workspace}/resume`                          |
| Usage for reconciliation      | `GET /usage?filter[workspace]=ws_…&filter[period]=2026-11`; `metrics["envelope.sent.by_channel"]` splits sends by channel |
| Your Platform allowance       | `GET /usage` without `Workspace-Id`: `platform.api_envelopes` (allowance used and left)   |
| Platform settings (read-only) | `GET /platform` with `platform:read`                                                     |
| Platform members (read-only)  | `GET /platform/members` (`filter[role]`); invitations and roles stay in the console      |
| Export a workspace            | `POST /workspaces/{ws}/exports` with `Workspace-Id` and the `workspaces:export` ability  |

A suspended workspace keeps its reads and its signing links already sent, but every write through the API or the app is blocked.

With a platform key, the MCP server has the same calls as tools: `list_workspaces`, `get_workspace`, `create_workspace`, `update_workspace`, `suspend_workspace`, `resume_workspace` and `remove_workspace_member` on a connection without `Workspace-Id`, and `start_workspace_export` and `get_workspace_export`, which name the workspace with `workspace_id`. See [MCP servers](/docs/mcp).

## 2. Keys

The simplest integration holds one platform key and names the workspace on each call:

```bash
curl "https://esignstack.app/api/v1/brand_kits/effective" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Workspace-Id: ws_01J8Z3Q4M7X2V5N9K6T1R0WABC"
```

For isolation, create a workspace key per customer with only the abilities its integration needs. Call with a platform key and no `Workspace-Id`. The secret is returned once.

```bash
curl -X POST "https://esignstack.app/api/v1/api_keys" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Idempotency-Key: customer-1001-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Dental server",
    "workspace": "ws_01J8Z3Q4M7X2V5N9K6T1R0WABC",
    "abilities": ["envelopes:read", "envelopes:write", "envelopes:send", "envelopes:void", "templates:read", "files:read", "files:write", "artifacts:read"],
    "expires_at": "2027-10-01T00:00:00Z"
  }'
```

- Abilities: `envelopes:read|write|send|void`, `templates:read|write`, `folders:read|write`, `files:read|write`, `webhooks:read|write`, `brand_kits:read|write`, `artifacts:read`, `usage:read`, `audit:read`, `keys:write`, `workspaces:export`. Platform keys only: `workspaces:read|write`, `platform:read`, `login_links:write`, `identity_providers:write`.
- A key can't grant abilities it doesn't have, and can't outlive its own expiry. The new key has the same mode as the key that created it, so a test key can only issue test keys.
- List keys with `GET /api_keys`, check the current key with `GET /api_keys/current`, revoke with `DELETE /api_keys/{key}`.
- In the console, only platform admins can create keys.

Create and action `POST`s take an `Idempotency-Key` (up to 255 characters), the deprovision endpoints included. Reuse it only to retry the same request; a different body with the same key returns `409 idempotency_key_reused`. Versions, errors and rate limits are in the [API quick start](/docs/api-authentication).

## 3. Branding

A brand kit holds logos, colors, radius, font and email wording. Set a platform default once and override it per customer; a workspace inherits every field it leaves empty.

```bash
# Platform default: platform key, no Workspace-Id
curl -X POST "https://esignstack.app/api/v1/brand_kits" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -F "name=Acme Platform" -F "primary_color=#1f4fd8" -F "radius_px=8" \
  -F "font=instrument-sans" -F "support_contact=help@example.com" \
  -F "logo_light=@logo-light.png"

# Customer override: same endpoint with Workspace-Id
curl -X POST "https://esignstack.app/api/v1/brand_kits" \
  -H "Authorization: Bearer $PLATFORM_KEY" -H "Workspace-Id: $WS" \
  -F "name=Acme Dental" -F "primary_color=#0a7d5a" -F "logo_light=@acme-dental.png"

# What signers will see
curl "https://esignstack.app/api/v1/brand_kits/effective" \
  -H "Authorization: Bearer $PLATFORM_KEY" -H "Workspace-Id: $WS"
```

- Colors are hex, the font is `instrument-sans`, `system` or `serif`, and the radius is bounded. Logos and icons accept PNG, JPEG, WebP or GIF, up to 5 MB, and are normalized to PNG. The app converts SVG in the browser. Branding changes need a live key; the sandbox uses the live kit.
- The platform default kit needs a live key to create, update or delete; a test key gets `403 live_key_required`. With `Workspace-Id`, a test key changes the kit of that workspace's sandbox, which starts as a copy of the live one.
- Each owner has one kit; update it with `PATCH /brand_kits/{kit}`. Send `null` for a field to inherit it again.
- `show_powered_by: false` hides the eSignStack credit in your workspaces.
- Admins can also edit the platform default under **Settings → Brand defaults** in the console.

## 4. Webhooks and catch-up

One platform endpoint receives events from all of your workspaces. Create it with a platform key and no `Workspace-Id`, or in the console under **Webhooks**:

```bash
curl -X POST "https://esignstack.app/api/v1/webhook_endpoints" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Idempotency-Key: platform-endpoint" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/esignstack", "enabled_events": ["*"] }'
```

Each event carries `platform` (`plat_…`) and `workspace` (`ws_…`), so you can route it to the right customer. Verify the signature (it's [Standard Webhooks](https://www.standardwebhooks.com), so its official libraries work), answer `2xx` within 15 seconds, and de-duplicate on `webhook-id`: deliveries can repeat and arrive out of order. Signature details are in [Webhooks and events](/docs/webhooks).

**Catch up after downtime.** Events stay available for 30 days. On startup and on a schedule, list what you missed and resend anything you didn't process:

```bash
curl -G "https://esignstack.app/api/v1/events" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  --data-urlencode "filter[created][gte]=2026-12-01T00:00:00Z" --data-urlencode "filter[type]=envelope.completed"

curl -X POST "https://esignstack.app/api/v1/events/evt_01J…/resend" \
  -H "Authorization: Bearer $PLATFORM_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{ "webhook_endpoint": "we_01J…" }'
```

Rotate the secret with `POST /webhook_endpoints/{id}/rotate_secret`; `expire_old_in` (up to 86,400 seconds) keeps the old secret valid meanwhile. If every delivery to an endpoint fails for 5 days, it's turned off. Check its status on the console's **Webhooks** page and turn it back on with **Enable** or `POST /webhook_endpoints/{id}/enable`.

## 5. Send envelopes

Use the platform key with `Workspace-Id`, or the customer's workspace key.

| Step                                    | Endpoint                                                          |
| --------------------------------------- | ----------------------------------------------------------------- |
| Upload a PDF                            | `POST /files` (`processing`, then `file.ready`)                   |
| Create a draft from the file            | `POST /envelopes`                                                 |
| Or create from one or more templates    | `POST /envelopes` with `templates`                                |
| Wait until the draft is prepared        | `envelope.prepared`, or `GET /envelopes/{envelope}`               |
| Add documents, recipients and fields    | `/envelopes/{envelope}/documents`, `/recipients`, `/fields`            |
| Preview, then send                      | `POST /envelopes/{envelope}/preview`, `POST /envelopes/{envelope}/send`     |
| Correct, remind, extend or void         | `/corrections`, `/remind`, `/extend`, `/void`                     |
| Get the signed files                    | `GET /envelopes/{envelope}/artifacts`                                  |

```bash
curl -X POST "https://esignstack.app/api/v1/envelopes" \
  -H "Authorization: Bearer $PLATFORM_KEY" -H "Workspace-Id: $WS" \
  -H "Idempotency-Key: case-77-create" -H "Content-Type: application/json" \
  -d '{ "file": "file_01J8Z3Q4M7X2V5N9K6T1R0WABC", "name": "Case 77", "external_id": "case-77" }'
```

The draft is answered at once with `preparation_status: "preparing"`. The file doesn't need to be ready yet. Add fields and send once it is `ready`; until then those requests answer `409 envelope_preparing` with `Retry-After`. With `send: true`, wait for `envelope.sent` before you create signing sessions. See [Preparation](/docs/envelopes#preparation).

On `envelope.completed`, call `GET /envelopes/{envelope}/artifacts` and download the files promptly; the URLs are short-lived. The full walkthrough is in the [Envelopes API](/docs/envelopes).

## 6. Signing and editor sessions

A **signing session** gives one recipient a URL to sign, hosted on eSignStack or embedded in your app. Create it on your server when the signer is ready:

```bash
curl -X POST "https://esignstack.app/api/v1/envelopes/$ENV/recipients/$RCP/signing_sessions" \
  -H "Authorization: Bearer $PLATFORM_KEY" -H "Workspace-Id: $WS" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{
    "mode": "embedded",
    "parent_origin": "https://acme.example.com",
    "actor": { "name": "Jane Doe", "email": "jane@example.com", "external_id": "staff_17" }
  }'
```

- `parent_origin` must be one of the workspace's `embed_allowed_origins`. A hosted `return_url` must be on the workspace's `signing_return_allowed_origins`, which you set when provisioning the workspace or a workspace admin sets under **Settings → Embedding**.
- The URL must be opened within 10 minutes. An open session lasts 60 minutes idle and 8 hours at most.
- `actor` is who your app says is acting; the audit trail records it as stated by your platform.
- The signing page uses the workspace's brand kit; `appearance` needs a plan with custom branding or a platform workspace, and can adjust `primary`, `radius`, `font` and `dark_mode`. The page background isn't themeable: `appearance.background` or a kit's `background_color` gets a `422`.

An **editor session** lets your user prepare a draft or template in eSignStack's editor without an eSignStack login, or start a new template there. See [Embedded signing](/docs/embed-integration) and [Editor sessions](/docs/editor-sessions). Templates, folders and filing rules belong to the workspace. In a workspace with no members they have no creator, so envelopes from their share links and kiosks have no sender, like API envelopes: nobody gets the sender's emails, so follow them with webhooks. See [Templates](/docs/templates).

## 7. Sign in your people

Your staff can open eSignStack without a separate password, two ways:

- **Open in eSignStack (login links):** your server requests a single-use link for a person and redirects them to it. They join the workspace as an ordinary member the first time.
- **Sign in with your platform:** register your OpenID Connect provider and people sign in with their platform account. Their memberships follow your provider's claims.

Both identify a person by your own ID, never by email. See [Platform sign-in](/docs/platform-sign-in).

When someone leaves one customer, remove them from that workspace with `DELETE /workspaces/{workspace}/members/{external_id}`; their sessions and other workspaces stay. When they leave your platform, `POST /login_identities/{external_id}/deprovision` removes them from all your workspaces and signs them out. Both need a live key with `login_links:write`. See [Remove a person](/docs/platform-sign-in#remove-a-person).

## Build order

1. Create a workspace with a live key and an `external_id`; retry it to see the same workspace come back. Then use a test key with its `Workspace-Id` to work in its sandbox for the steps below.
2. Create a brand kit and check `GET /brand_kits/effective`.
3. Create a platform webhook endpoint, verify signatures, and add the `GET /events` catch-up job.
4. Wire the envelope flow with idempotency keys, then download artifacts on `envelope.completed`.
5. Add signing sessions, hosted first, then embedded.
6. Add an Open in eSignStack button (login links), then OIDC if your people also go straight to eSignStack.
7. Create a workspace key per customer and keep the platform key for platform-level work.
