Skip to content

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.

Embedded signing, from envelope to confirmed signature
Your page
Your server
SignatureAPI
Ceremony iframe
  1. Your page to Your server: The signed-in user asks to sign
  2. Your server to SignatureAPI: Create envelope POST /v1/envelopes
  3. SignatureAPI to Your server: 201 Created with recipients[].ceremony.url
  4. SignatureAPI to Your server: Webhook envelope.started
  5. Your server to Your page: Return the ceremony URL
  6. Your page to Ceremony iframe: Load the URL in an iframe
  7. Ceremony iframe: The recipient reviews and signs
  8. Ceremony iframe to Your page: Message ceremony.completed
  9. SignatureAPI to Your server: Webhook recipient.completed
  1. The signed-in user asks to sign

    Your server already knows who the user is. The browser never holds your API key.

  2. Create envelope POST /v1/envelopes

    Give the recipient custom authentication so SignatureAPI returns the ceremony URL instead of emailing it, and list your page's origin in ceremony.embeddable_in.

    Show the request
    HTTP
    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"]
          }
        }
      ]
    }
  3. 201 Created with recipients[].ceremony.url

    The envelope starts in processing. The URL is already in the response, but the ceremony opens only once the envelope is in_progress.

  4. Webhook envelope.started

    The envelope is now in_progress. Instead of a webhook, you can read the envelope with GET /v1/envelopes/{id} until its status is in_progress.

  5. 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.

  6. Load the URL in an iframe

    Append embedded=true and event_delivery=message to the URL.

  7. Message ceremony.completed

    Accept it only when event.origin is https://sign.signatureapi.com and event.source is the iframe. Use it to update your page.

  8. Webhook recipient.completed

    The 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.

Signing in an iframe · 0:11

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:

  • authentication starts with custom: 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 in data; they appear in the audit log. See Custom authentication.
  • embeddable_in lists the origins allowed to show the ceremony in an iframe. Without it, the browser refuses to load the iframe.
HTTP
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:

201 Created
{
  "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.

Never call the API from the browser. Your API key would be exposed to anyone using your app, giving them access to all your data in SignatureAPI. Make API calls from your server and pass only the ceremony URL to the page.

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=true lays out the ceremony for an iframe and sends the frame-ancestors directive of the built from embeddable_in.
  • event_delivery=message sends 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=message

Add them with the URL API rather than string concatenation:

JavaScript
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.

Ensure you use the URL with the embedded=true and event_delivery=message query parameters appended.
HTML
<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.

Embedder tool with a ceremony URL field, width and height fields, and the ceremony preview in an iframe below them

To use the Embedder:

  1. Go to the Embedder Tool.
  2. Enter your ceremony URL. The Embedder adds embedded=true and event_delivery=message for you.
  3. Optionally, adjust the width and height in pixels.
  4. 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.

JavaScript
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);
A 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=true query parameter is present. Without it, the correct CSP headers are not set and the browser blocks the iframe.
  • embeddable_in is 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) in embeddable_in during development.
  • Multiple origins. If your app runs on multiple domains, include all of them in the embeddable_in array.

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:

HTTP
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": [
    "*"
  ]
}
Do not use the * wildcard in production. It allows any website to embed your signing ceremony, which is a security risk.

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