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

### Create the link

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](/docs/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`.
