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:
- Your server calls
POST /api/v1/login_linksfor that person and that customer's workspace. - Your server redirects the browser to the
urlin the response within 60 seconds. - The person lands in the workspace, signed in to their own eSignStack account.
Create the link
Call with a live platform key that has the login_links:write ability:
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:
{
"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
DELETE /api/v1/workspaces/ws_01J8Z3Q4M7X2V5N9K6T1R0WABC/members/user_4821
Authorization: Bearer sk_live_…{
"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
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 roleper line, such asdirector=admin. Workspace roles areadminormember. - Platform role claim (optional): a claim that grants console roles (
admin,developer,billingorsupport). Each grant is audited. - Console MFA (optional): accepted
amrand/oracrvalues. 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 (
noneand HMAC are refused); - have
issexactly equal to the registered issuer, andaudcontaining the client ID (withazpequal to it when there are several audiences); - pass
exp,iatandnoncechecks, allowing two minutes of clock skew; - include
emailandemail_verifiedas the booleantrue.
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 thesub). - Deprovision: call
POST /api/v1/identity_providers/{provider}/subjects/{sub}/deprovisionwith 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.