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_…`) in the key's mode. A test key opens test envelopes and templates. A sent envelope returns `409`; use corrections instead.
`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. 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.

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.

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.

Confirm what happened

Messages and redirects only update your interface. Check the result with GET /api/v1/envelopes/{id} or the envelope.sent webhook before acting on it.