Skip to content
On this page

Platforms

Markdown

Platform sign-in

Let your people open your customer workspaces in eSignStack from your app, with an "Open in eSignStack" button or with your own OpenID Connect provider.

A platform has two ways to sign its people in without a separate eSignStack password:

  • Open in eSignStack (login links): your server asks for a single-use link for one person and one workspace, then redirects them to it.
  • Sign in with your platform (OIDC): you register your OpenID Connect provider, and people sign in with their platform account.

Both identify a person by your own ID for them, never by email.

Note

Login links work as soon as you have a live platform key with the login_links:write ability. Sign in with your platform (OIDC) is off until eSignStack turns it on for your platform; until then your sign-in page isn't available.

Open in eSignStack

Put an Open in eSignStack button on a customer's page in your app. When someone clicks it:

  1. Your server calls POST /api/v1/login_links for that person and that customer's workspace.
  2. Your server redirects the browser to the url in the response within 60 seconds.
  3. The person lands in the workspace, signed in to their own eSignStack account.

Call with a live platform key that has the login_links:write ability:

http
POST /api/v1/login_links
Authorization: Bearer sk_live_…
Content-Type: application/json

{
  "workspace": "ws_01J8Z3Q4M7X2V5N9K6T1R0WABC",
  "actor": {
    "external_id": "user_4821",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "role": "member",
    "email_verified": true
  },
  "return_to": "/acme-dental/envelopes"
}
Field Notes
workspace A workspace your platform owns.
actor.external_id Your ID for the person. Required. Keep it stable: it's how we recognise them next time.
actor.email Required.
actor.name Optional. Used as the name of a new account.
actor.role admin, developer or member, never owner. Used only when the person first joins the workspace.
actor.email_verified Set true only if you verified the address yourself. Defaults to false.
return_to Optional path in eSignStack to land on, such as /acme-dental/envelopes. Full URLs are rejected.

The response is 201:

json
{
  "id": "ll_01J8Z3R2K4N6P8Q0S2T4V6X8YZ",
  "created": "2026-10-24T15:04:05+00:00",
  "workspace": "ws_01J8Z3Q4M7X2V5N9K6T1R0WABC",
  "url": "https://esignstack.app/sso/link/…",
  "expires_at": "2026-10-24T15:05:05+00:00",
  "object": "login_link"
}

The url works once and expires after 60 seconds, so create it when the button is clicked, never in advance. Without return_to, the person lands on the workspace dashboard.

Status error.code When
401 authentication_required Missing or invalid key.
403 permission_denied The key isn't a platform key or lacks login_links:write.
403 live_key_required A test key. People are always added to the live workspace.
404 resource_missing The workspace isn't one your platform owns.
422 validation_failed A missing field, role of owner or unknown, or a return_to that isn't a path.

When the browser opens the link, eSignStack answers with a page instead of signing in when the link was already used or expired (410), when the email already has an eSignStack account and needs confirming (202, see below), or when the sign-in is refused (403).

Members, not guests

The first time a person opens a workspace, they join it as an ordinary member with the role you sent. After that, their membership is like anyone else's:

  • Later links don't change their role or membership, even with a different role.
  • The workspace's admins, if it has any, and you through the console or API manage them like any other member.
  • If someone removes them from the workspace, the next link adds them again with the role in that link.

Each person has their own eSignStack account. Besides your button, they can sign in at eSignStack directly with a password or Google.

Account setup prompt

Someone whose account was created by a login link has no password. The first time they arrive through a link, eSignStack asks them to set a password or connect a Google account. Any Google account works, even one with a different email: they'll sign in with that Google account from then on. The prompt goes away once they do either or dismiss it. They can still reset a password later from the sign-in page.

First sign-in with an existing email

  • New email: we create an eSignStack account and add the person to the workspace. Without email_verified: true, the account's email stays unverified and envelopes already sent to that address aren't linked to it.
  • Email already has an eSignStack account: nothing is linked silently. If you sent email_verified: true, we email that address a confirmation link (valid for 60 minutes); once the account holder confirms, the sign-in is linked and they're added to the workspace. If you didn't, the sign-in is refused.
  • Existing account whose email was never verified: confirming takes the account over. Its password stops working, two-factor authentication is removed and its other sessions end.

Remove a person

When someone leaves one of your customers, remove them from that customer's workspace. When they leave your platform altogether, deprovision them.

To Call What ends
Remove from one workspace DELETE /api/v1/workspaces/{workspace}/members/{external_id} That workspace membership. Their sessions and other workspaces stay.
Remove everywhere POST /api/v1/login_identities/{external_id}/deprovision Every membership in your workspaces, and their platform sessions.

Both need a live platform key with login_links:write and remove memberships however they were added: by a login link, an invitation or the console. Their eSignStack account, workspaces of their own and your workspaces' documents are untouched. A later login link adds them again.

From one workspace

http
DELETE /api/v1/workspaces/ws_01J8Z3Q4M7X2V5N9K6T1R0WABC/members/user_4821
Authorization: Bearer sk_live_…
json
{
  "id": "user_4821",
  "object": "workspace_member",
  "workspace": "ws_01J8Z3Q4M7X2V5N9K6T1R0WABC",
  "deleted": true
}

The member is your external_id for the person. If they're in that workspace right now, their next page or request there is refused; they stay signed in and keep their other workspaces. Their access to the workspace's sandbox goes too.

Status error.code When
403 live_key_required A test key. Members are managed on the live workspace.
404 resource_missing The workspace isn't yours (param: workspace), or the person isn't a member of it or never used a login link (param: member). A repeated call answers this, so treat it as done.
409 resource_conflict The person owns the workspace.

From every workspace

http
POST /api/v1/login_identities/user_4821/deprovision
Authorization: Bearer sk_live_…

This removes user_4821 from every workspace your platform owns and ends their platform sessions at once. The response is {"object": "deprovision_result", "identity_provider": null, "external_id": "user_4821", "memberships_removed": 2}; the identity-provider endpoint answers the same shape with its provider in identity_provider. It's 404 for an external_id that never used a login link.

Sign in with your platform (OIDC)

Register your provider

A platform admin opens Sign-in (identity provider) in the platform console and fills in:

  • Display name and an optional Logo URL, shown on your sign-in page.
  • Issuer: your HTTPS issuer URL, exactly as it appears in your discovery document. We read the discovery document and signing keys when you save, and pin them.
  • Client ID and Client secret.
  • Tenant claim (default tenants): the ID token claim that lists the person's workspaces.
  • Role mapping: one your role=workspace role per line, such as director=admin. Workspace roles are admin or member.
  • Platform role claim (optional): a claim that grants console roles (admin, developer, billing or support). Each grant is audited.
  • Console MFA (optional): accepted amr and/or acr values. When set, platform admins must sign in through your provider with a matching value to open the console.

After saving, the page lists what to give your provider and where to link people:

Setting Value
Redirect URI https://esignstack.app/sso/{provider}/callback
Back-channel logout URI https://esignstack.app/sso/{provider}/backchannel-logout
Start sign-in https://esignstack.app/sso/{provider}/start
Your sign-in page https://esignstack.app/login/{your-platform}

Disable turns the provider off, and saving it turns it back on. You can also manage it with the API (/identity_providers, live platform key with identity_providers:write): POST /identity_providers/{id}/disable and POST …/enable turn it off and on, and updating it keeps its status.

The sign-in flow

We use the authorization code flow with PKCE (S256), state and nonce, scope openid email profile, and send the client secret in the token request body. A sign-in must finish within 10 minutes of starting.

The ID token must:

  • be signed with RS256 or ES256 by a key in your published key set (none and HMAC are refused);
  • have iss exactly equal to the registered issuer, and aud containing the client ID (with azp equal to it when there are several audiences);
  • pass exp, iat and nonce checks, allowing two minutes of clock skew;
  • include email and email_verified as the boolean true.

A person is identified by your issuer and their sub. The same account rules as login links apply: an existing account with the same email is linked only after its holder confirms by email.

Claims

Claim Used for
sub The person's ID. Required.
email, email_verified Account email. email_verified must be true.
name Display name for a new account.
Tenant claim [{ "external_id": "customer_1001", "role": "director" }]
sid Lets back-channel logout end one session.
amr, acr Checked against Console MFA, if set.
Platform role claim Grants a console role, if configured.

Each external_id matches only a workspace of your platform with that external ID. Each role goes through the role mapping; admin and member pass through unmapped, any other unmapped role grants nothing, and owner is never granted.

Membership sync

Memberships are synced at every OIDC sign-in: added, role-updated, or removed when the tenant claim no longer lists the workspace. Only memberships your provider added are synced; members added by hand or by login links are never touched. A person with no workspace who isn't a platform member is refused.

Sign-out and removal

  • Back-channel logout: when your provider posts a logout token to the back-channel logout URI, we end the matching platform sessions at once (by sid, or every session for the sub).
  • Deprovision: call POST /api/v1/identity_providers/{provider}/subjects/{sub}/deprovision with a live platform key. It removes the memberships your provider manages for that person and ends their platform sessions.

Signing in other ways

Members of your workspaces can open them from any eSignStack sign-in, like any other workspace: a login link, your provider, a password or Google. Platform sign-in adds and removes people; it doesn't decide how they sign in afterwards.

A session started by a login link or your provider lasts like any other eSignStack session, and ends at once when you deprovision the person or your provider sends a back-channel logout. To take someone's access away, remove them from the workspace or deprovision them: either takes effect whichever way they sign in. Tenant claims only sync when they sign in through your provider.

Audit log

Each step is recorded in the console's Audit log, including sso.login_link_issued, sso.signed_in, sso.user_provisioned, sso.membership_granted, sso.membership_role_changed, sso.membership_revoked, sso.account_link_requested, sso.account_link_confirmed, sso.platform_role_granted, sso.sessions_revoked, sso.deprovisioned, sso.sign_in_refused and identity_provider.updated.