# Editor sessions

Let your users prepare a draft envelope or a template in the eSignStack editor, inside your app or on a hosted page, without an eSignStack account.

Your server creates an editor session and gets back a single-use URL. You load it in an iframe (`embedded`) or send the browser to it (`hosted`). The person can only do what the session allows.

## Create a session

```http
POST /api/v1/editor_sessions
Authorization: Bearer rk_live_…
Content-Type: application/json
Idempotency-Key: order-456-edit-1

{
  "target": "env_01J…",
  "mode": "embedded",
  "parent_origin": "https://app.example.com",
  "capabilities": { "edit_documents": true, "edit_recipients": true, "edit_fields": true, "send": false },
  "actor": { "name": "Jane Doe", "email": "jane@example.com", "external_id": "user_123" }
}
```

| Field           | Notes                                                                 |
| --------------- | --------------------------------------------------------------------- |
| `target`        | A draft envelope (`env_…`) or a template (`tpl_…`). A test key opens the sandbox's envelopes and templates, and a live key the live ones. A sent envelope returns `409`; use [corrections](/docs/envelopes#corrections) instead. A new one must be [prepared](/docs/envelopes#preparation) first (`preparation_status: "ready"`); until then it returns `409 envelope_preparing` or `template_preparing`. |
| `new_template`  | Instead of `target`: start a new template. See [Start a new template](#start-a-new-template). |
| `mode`          | `embedded` or `hosted`                                                |
| `parent_origin` | Required for `embedded`. Must be an origin in **Settings → Embedding**. |
| `return_url`    | Required for `hosted`. Must be an HTTPS URL on an allowed return origin. |
| `capabilities`  | At least one of `edit_documents`, `edit_recipients`, `edit_fields` and `send`. |
| `actor`         | Who your app says is editing: the same `actor` as on envelope create and send (`name` required, `email`, `external_id`). Recorded with every change in the history. |

Capabilities can't go beyond the key. Editing an envelope needs `envelopes:write`, editing a template needs `templates:write`, and `send` needs `envelopes:send`. Templates can't be sent. The server checks the capability and the key's ability on every change, so removing an ability from the key stops those changes in open sessions.

The response includes `id` (`ses_…`), `url` and `expires_at`. Open the URL within 10 minutes. After that the session lasts 60 minutes without activity and 8 hours at most. It also ends if the key that created it expires or is revoked.

## Saving

The editor saves as the person works, as it does for your own team. **Done** saves anything still waiting and ends the session with `saved`. If something can't be saved yet, such as a field with nobody to fill it, the editor says so and stays open. **Cancel** ends the session with `cancelled`. Changes already saved are kept.

A link that can no longer be used shows a short note instead of the editor: the session ended or expired, or the entry link was already opened. The note asks the person to open the editor again from your app.

## Edit a template

Templates have three steps: **Documents** (add files, reorder, rotate and remove pages, and choose whether a fillable PDF keeps its fields), **Roles** (names such as "Next of kin"; no email needed) and **Fields**. A **Sender pre-fill** field is filled in before sending, by whoever creates an envelope from the template, for example through `POST /templates/{id}/envelopes` with `values`. Templates have no Send step, and their share link and kiosk settings aren't shown.

## Start a new template

Send `new_template` instead of `target`:

```json
{
  "new_template": { "name": "Cremation Authorization", "metadata": { "form": "cremation-v2" } },
  "mode": "hosted",
  "return_url": "https://app.example.com/after-edit",
  "capabilities": { "edit_documents": true, "edit_recipients": true, "edit_fields": true }
}
```

The person starts on an empty Documents step. Their first file creates the template with your `name` and `metadata`. The session then edits that template. Until then, `target` is `null` in the response, and no template exists.

- `edit_documents` is required, so the person can add the first file.
- The key needs `templates:write`, and the workspace plan must include templates.
- As with `POST /templates`, the template belongs to the workspace. In a workspace with no members it has no creator.
- If the person leaves before adding a file, nothing is created and the hand-back has no `target`.

## Embedded sessions

Put the URL in an iframe. The page can only be framed by `parent_origin`. The editor posts messages to that origin, with the name in a `type` key:

| `type`                       | When                                     |
| ---------------------------- | ---------------------------------------- |
| `esignstack:editor.ready`    | The editor loaded                        |
| `esignstack:editor.saved`    | The person saved and finished            |
| `esignstack:editor.sent`     | The person sent the envelope             |
| `esignstack:editor.cancelled`| The person left without saving           |
| `esignstack:resize`          | The content height changed (`height`)    |

Each message also has `session`. `editor.saved` and `editor.cancelled` also have `target`: the envelope or template ID, or `null` when a session that starts a template ended before its first file.

## Hosted sessions

When the person finishes, the browser goes to:

```text
https://app.example.com/after-edit?session=ses_…&status=saved&target=env_…
```

`status` is `saved`, `sent` or `cancelled`. `target` is left out when a session that starts a template ended before its first file.

## Confirm what happened

Messages and redirects only update your interface. Check the result before acting on it: `GET /api/v1/envelopes/{id}` or the `envelope.sent` [webhook](/docs/webhooks) for envelopes, and `GET /api/v1/templates/{id}?expand[]=roles&expand[]=fields` or the `template.created` and `template.updated` webhooks for templates.
