Embed tokens

Partners mint short-lived JWTs so their customers can load the Loyva sign or vault widget directly inside the partner's UI. Tokens are scoped to a single envelope and widget type and expire in 15 minutes.

info

This endpoint is live and can be called today. The companion JavaScript SDK (@loyva/embed) and the iframe host that renders the widget are in progress — contact your Loyva point of contact before designing an embedded signing flow so we can coordinate when the frontend pieces are ready.

Mint an embed token

POST /embed/token

Auth: X-API-Key: lk_<partner key>

Request body:

Field	Type	Required	Description
`envelope_id`	string	Yes	Envelope owned by the same org as the API key
`user_email`	string (email)	Yes	End-user loading the widget (recorded on the token)
`widget_type`	enum	Yes	`sign` or `vault`

Required scope:

Widget	Scope
`sign`	`esign:write`
`vault`	`vault:read`

Envelope status requirements:

Widget	Allowed envelope status
`sign`	`sent` or `viewed`
`vault`	Vaulted (has a stored `vault_file_path`)

Response (200):

{
  "data": {
    "token": "eyJhbGciOi...<signed JWT>",
    "expires_at": "2026-04-11T10:15:00.000Z",
    "embed_url": "https://embed.stg.loyva.net/sign/env_x7k9m2p4q1w3#token=eyJhbGciOi...",
    "widget_type": "sign",
    "envelope_id": "env_x7k9m2p4q1w3"
  }
}

The token is pre-appended to embed_url as a fragment (#token=...), so the fragment never hits your server logs. You can hand the URL directly to the embed SDK or construct your own iframe.

Code	Meaning
`403`	API key missing the required scope
`404`	Envelope does not exist in the partner's org
`409`	Envelope status incompatible with the requested widget
`422`	Validation failed (invalid email, unknown `widget_type`)

Example

curl -X POST https://api.stg.loyva.net/api/v2/embed/token \
  -H "X-API-Key: lk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "envelope_id": "env_x7k9m2p4q1w3",
    "user_email": "[email protected]",
    "widget_type": "sign"
  }'

Once you have the token, return the embed_url to your frontend. The browser loads it in an iframe; the #token=... fragment authenticates the session against the Loyva signing host.

<iframe src="https://embed.stg.loyva.net/sign/env_x7k9m2p4q1w3#token=eyJ..."
        style="width: 100%; height: 600px; border: 0;"
        allow="clipboard-write"></iframe>

A drop-in JavaScript SDK (@loyva/embed) with React/Vue bindings, lifecycle callbacks, and postMessage plumbing is in progress — it will wrap the iframe setup so partners don't hand-roll it. Track status with your Loyva point of contact.

Mint an embed token​

Example​

Mint an embed token

Example