Skip to content
On this page

Platforms

Markdown

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.

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: 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 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.

  • 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. 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.

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 POSTs 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.

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, 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.

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.

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.

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 and 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.

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.

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.

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.