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
- Talk to us about your platform. We agree a Platform plan for the account that will pay for it.
- We create your platform, link it to that paying account and make you its first admin.
- 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_reacheduntil 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.
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-Idto the/workspacesendpoints. Store the returnedid(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'sWorkspace-Idworks in its sandbox, which is made on first use. Responses still name the workspace'sws_…ID, withlivemode: false. Test envelopes are watermarked and never billed. - The sandbox starts with a copy of the workspace's
settingsandnotification_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 andPATCH /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, withlivemode: false.nameandmetadataare the same on both sides: a test key sending them gets403 live_key_requiredwithparamnaming the attribute. settingsacceptsembed_allowed_originsandsigning_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) (nulluses the default) andrequire_esign_consent(whether signers must agree to the disclosure before signing). A workspace'ssettingsreads the same onGET /workspaces/{workspace}and onGET /workspacewith the workspace's own key, which can change the defaults (PATCH /workspace) but not the origins or disclosure wording.notification_policysays who sends each email:esignstack(we send it) orhost(we stay silent; you notify people yourself).PATCHchanges only the kinds you send; null for a kind goes back toesignstack. Kinds:signing_request,reminder,sequential_handoff,completed_copy_recipients,completed_copy_cc,owner_completed,delivery_problem,declined,voided.metadatatakes up to 20 string key/value pairs. Don't store secrets there.brand_kittakes an object of kit fields, ornullto 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:
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.
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 withGET /api_keys/current, revoke withDELETE /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.
# 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,systemorserif, 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. WithWorkspace-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}. Sendnullfor a field to inherit it again. show_powered_by: falsehides 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:
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:
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 |
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:
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_originmust be one of the workspace'sembed_allowed_origins. A hostedreturn_urlmust be on the workspace'ssigning_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.
actoris 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;
appearanceneeds a plan with custom branding or a platform workspace, and can adjustprimary,radius,fontanddark_mode. The page background isn't themeable:appearance.backgroundor a kit'sbackground_colorgets a422.
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
- 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 itsWorkspace-Idto work in its sandbox for the steps below. - Create a brand kit and check
GET /brand_kits/effective. - Create a platform webhook endpoint, verify signatures, and add the
GET /eventscatch-up job. - Wire the envelope flow with idempotency keys, then download artifacts on
envelope.completed. - Add signing sessions, hosted first, then embedded.
- Add an Open in eSignStack button (login links), then OIDC if your people also go straight to eSignStack.
- Create a workspace key per customer and keep the platform key for platform-level work.