Platforms
Embedding in a Web Application
Embed the signing ceremony in your web app with an iframe. Create the envelope on your server, allow your origin, show the ceremony and handle its events.
Your web app shows the signing ceremony in an <iframe>, so the recipient signs without leaving your page. Your server creates the envelope with your API key and returns the ceremony URL; your page shows that URL and listens for the event that tells it how the ceremony ended.
- Your page to Your server: The signed-in user asks to sign
- Your server to SignatureAPI: Create envelope
POST /v1/envelopes - SignatureAPI to Your server:
201 Createdwithrecipients[].ceremony.url - SignatureAPI to Your server: Webhook
envelope.started - Your server to Your page: Return the ceremony URL
- Your page to Ceremony iframe: Load the URL in an iframe
- Ceremony iframe: The recipient reviews and signs
- Ceremony iframe to Your page: Message
ceremony.completed - SignatureAPI to Your server: Webhook
recipient.completed
- The signed-in user asks to sign
Your server already knows who the user is. The browser never holds your API key.
- Create envelope
POST /v1/envelopesGive the recipient
customauthentication so SignatureAPI returns the ceremony URL instead of emailing it, and list your page's origin inceremony.embeddable_in.Show the request
HTTPPOST /v1/envelopes HTTP/1.1 Host: api.signatureapi.com X-API-Key: YOUR_API_KEY Content-Type: application/json { "title": "Service Agreement", "documents": [ { "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf", "format": "pdf", "places": [ { "key": "signer_signs_here", "type": "signature", "recipient_key": "client" } ] } ], "recipients": [ { "type": "signer", "key": "client", "name": "Jane Doe", "email": "jane.doe@example.com", "ceremony": { "authentication": [ { "type": "custom", "provider": "Acme Portal", "data": { "user_id": "usr_12345" } } ], "embeddable_in": ["https://app.acme.example"] } } ] } 201 Createdwithrecipients[].ceremony.urlThe envelope starts in
processing. The URL is already in the response, but the ceremony opens only once the envelope isin_progress.- Webhook
envelope.startedThe envelope is now
in_progress. Instead of a webhook, you can read the envelope withGET /v1/envelopes/{id}until its status isin_progress. - Return the ceremony URL
The URL works like a password for this recipient: send it only to the signed-in user, and don't log it.
- Load the URL in an iframe
Append
embedded=trueandevent_delivery=messageto the URL. - Message
ceremony.completedAccept it only when
event.originishttps://sign.signatureapi.comandevent.sourceis the iframe. Use it to update your page. - Webhook
recipient.completedThe message comes from the browser and the webhook from SignatureAPI, so the two can arrive in either order. Treat the webhook, or a read of the envelope, as the record that the recipient signed.
Dashed: a reply, or an asynchronous call such as a webhook.
Using a framework? The same steps, with components and server code, are in the guides for React, Next.js, Vue and Nuxt, Angular and Svelte.
Create the envelope on your server
Create the envelope on your server. Two settings on the recipient’s ceremony make it embeddable:
authenticationstarts withcustom: your app has already signed the user in, so SignatureAPI returns the ceremony URL instead of emailing it. Put references to your own login session indata; they appear in the audit log. See Custom authentication.embeddable_inlists the origins allowed to show the ceremony in an iframe. Without it, the browser refuses to load the iframe.
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"title": "Service Agreement",
"documents": [
{
"url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/privacy-placeholder.pdf",
"format": "pdf",
"places": [
{
"key": "signer_signs_here",
"type": "signature",
"recipient_key": "client"
}
]
}
],
"recipients": [
{
"type": "signer",
"key": "client",
"name": "Jane Doe",
"email": "jane.doe@example.com",
"ceremony": {
"authentication": [
{
"type": "custom",
"provider": "Acme Portal",
"data": {
"user_id": "usr_12345"
}
}
],
"embeddable_in": [
"https://app.acme.example"
]
}
}
]
}Write each embeddable_in entry as an origin: the scheme, the host and the port if it isn’t the default, such as https://app.acme.example or http://localhost:3000 for local development. A path after the host is ignored. A wildcard covers subdomains, such as https://*.acme.example. You can list up to 10 origins.
SignatureAPI keeps embeddable_in only when the ceremony’s first authentication method is custom or email_code. With email_link first, the recipient gets the link by email and the ceremony can’t be embedded.
The 201 Created response already includes the ceremony URL in recipients[].ceremony.url. The response below is trimmed to the recipient:
{
"id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"title": "Service Agreement",
"status": "processing",
"recipients": [
{
"id": "re_49r1R2jpPDz8hSpP75ZkPp",
"envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
"type": "signer",
"key": "client",
"name": "Jane Doe",
"email": "jane.doe@example.com",
"status": "pending",
"ceremony": {
"authentication": [
{
"type": "custom",
"provider": "Acme Portal",
"data": {
"user_id": "usr_12345"
}
}
],
"embeddable_in": [
"https://app.acme.example"
],
"redirect_url": null,
"redirect_delay": 3,
"url_variant": "standard",
"url": "https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR..."
}
}
]
}The envelope starts in processing. The ceremony opens once the envelope is in_progress; if your page shows it earlier, the ceremony asks the recipient to try again later. Return the URL to your page after the envelope.started webhook, or after reading the envelope with GET /v1/envelopes/{id} and seeing in_progress. Every read returns a new URL for the same ceremony; any of them works.
The ceremony URL lets whoever holds it sign as the recipient. Send it only to the signed-in user it belongs to, and don’t log it.
The ceremony URL
Add two query parameters to the ceremony URL:
embedded=truelays out the ceremony for an iframe and sends theframe-ancestorsdirective of the built fromembeddable_in.event_delivery=messagesends ceremony events, such as completion, to your page as JavaScript messages.
Example URL with both query parameters:
https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjI4OTE3NDYsImV4cCI6MTcyMzQ5NjU0NiwiY2VyZW1vbnlf&embedded=true&event_delivery=messageAdd them with the URL API rather than string concatenation:
const url = new URL(ceremonyUrl);
url.searchParams.set('embedded', 'true');
url.searchParams.set('event_delivery', 'message');
iframe.src = url.toString();Other query parameters change the accent color and the Cancel button. See Ceremony Customization.
The <iframe> tag
Embed the signing interface using an iframe tag with the Ceremony URL as the src attribute.
embedded=true and event_delivery=message query parameters appended.<iframe
id="signatureapi-ceremony"
title="SignatureAPI Signing Ceremony"
width="800"
height="600"
src="https://sign.signatureapi.com/en/start?token=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjI4OTE3NDYsImV4cCI6MTcyMzQ5NjU0NiwiY2VyZW1vbnlf&embedded=true&event_delivery=message">
</iframe>Testing with Embedder
Before you build the page, preview your ceremony in an iframe with the Embedder tool.
To use the Embedder:
- Go to the Embedder Tool.
- Enter your ceremony URL. The Embedder adds
embedded=trueandevent_delivery=messagefor you. - Optionally, adjust the width and height in pixels.
- The Embedder shows your ceremony in an iframe of that size.
The Embedder runs on its own origin, so add https://signatureapi.github.io to the ceremony’s embeddable_in while you test with it.
Listening to events
The embedded ceremony sends JavaScript MessageEvents for events happening inside the ceremony.
Your app can listen to these events and take actions, such as closing the iframe when the ceremony is completed. The ceremony posts each message with a target origin of *. The payload carries no secrets, but your page must check who sent it. Accept a message only when event.origin is https://sign.signatureapi.com and event.source is the iframe’s contentWindow.
const iframe = document.getElementById('signatureapi-ceremony');
const CEREMONY_ORIGIN = 'https://sign.signatureapi.com';
// Function to handle the ceremony completed event
function handleCeremonyCompleted(event) {
console.log("Ceremony completed successfully.");
// Confirm the outcome on your server before acting on it
}
// Function to handle the ceremony canceled event
function handleCeremonyCanceled(event) {
console.log("Ceremony was canceled by the user.");
}
// Function to handle the ceremony declined event
function handleCeremonyDeclined(event) {
console.log("Ceremony was declined.");
}
// Function to handle the ceremony failed event
function handleCeremonyFailed(event) {
const { error_type, error_message } = event.data;
console.error(`Ceremony failed with error: ${error_type} - ${error_message}`);
}
// Function to handle incoming message events
function handleMessage(event) {
// Ignore messages that do not come from the ceremony iframe
if (event.origin !== CEREMONY_ORIGIN) return;
if (event.source !== iframe.contentWindow) return;
const { type } = event.data;
switch (type) {
case 'ceremony.completed':
handleCeremonyCompleted(event);
break;
case 'ceremony.canceled':
handleCeremonyCanceled(event);
break;
case 'ceremony.declined':
handleCeremonyDeclined(event);
break;
case 'ceremony.failed':
handleCeremonyFailed(event);
break;
default:
console.warn(`Unknown event type: ${type}`);
}
}
// Add event listener to window for message events
window.addEventListener('message', handleMessage, false);ceremony.completed event is a signal for your UI, not proof that the envelope is complete. Confirm the outcome on your server before you act on it.Troubleshooting
CSP frame-ancestors error
If the browser refuses to load the iframe and you see an error like this in the console:
Refused to frame … because an ancestor violates the following Content Security Policy directive: “frame-ancestors none”.
Check the following:
embedded=truequery parameter is present. Without it, the correct CSP headers are not set and the browser blocks the iframe.embeddable_inis set correctly. The array must include the exact origin where your app is hosted (for example,https://app.acme.example). Include the protocol (https://) and omit trailing slashes or paths.- Localhost testing. Use
http://localhost:3000(with your port number) inembeddable_induring development. - Multiple origins. If your app runs on multiple domains, include all of them in the
embeddable_inarray.
To isolate the issue, create a test ceremony with embeddable_in set to ["*"], which allows any origin. If that ceremony loads, the origin list of the original one is wrong. Use Create Ceremony to give the recipient a new ceremony:
POST /v1/recipients/re_49r1R2jpPDz8hSpP75ZkPp/ceremonies HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json
{
"authentication": [
{
"type": "custom",
"provider": "Acme Portal",
"data": {
"user_id": "usr_12345"
}
}
],
"embeddable_in": [
"*"
]
}The ceremony says to try again later
The envelope is still processing. Show the ceremony after the envelope.started webhook, or once a read of the envelope returns in_progress.
Keep learning
- Ceremony Events: every event, its payload and when it arrives.
- Ceremony Customization: accent color, Cancel button and result page delay.
- Authentication methods: how recipients prove who they are before signing.
- iOS, Android, React Native and Flutter: embed the ceremony in a mobile app.