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": "john@acme.com",
    "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.

Sign + Pay

An org can request a one-time payment on an envelope (set when the document is prepared). When the designated signer completes signing in the embed, the Loyva signing host collects the payment with a Stripe Payment Element before forwarding the final completion event. Funds are a destination charge routed to the org's Stripe Connect account; Loyva's platform fee is taken as the application_fee.

These two endpoints are called by the Loyva embed host itself (the embed JWT is the credential — no X-API-Key). Partners don't call them directly; they're documented here for completeness.

POST /embed/payment-intent

Returns payment_required: false when no payment is due or the verified signer is not the designated payer (the host then skips the step). Otherwise returns a Stripe client_secret + publishable key for the Payment Element.

{ "data": { "payment_required": true, "client_secret": "pi_..._secret_...", "publishable_key": "pk_test_...", "amount_cents": 2500, "currency": "usd", "status": "requires_payment" } }

POST /embed/payment-status

Polls the payment state after confirmation (requires_payment → paid once the payment_intent.succeeded webhook lands). Returns { "data": { "status": "paid" } } (or null when no payment was requested).

Vault gating: a vault embed token is refused (409) while a requested payment is unsettled, and the synchronous vault-in endpoints (/envelopes/:id/vault-in-signed, /envelopes/:id/vault-in-upload) return 409 until the payment is paid. The authoritative UCC §9-105 copy is never created before the money settles. Payment is not a UCC §9-105 compliance check — it only adds a business precondition.