---
title: "Introduction"
description: "Let users sign inside your web or mobile app. Your server creates the ceremony, your app shows it in an iframe or WebView and reacts to how it ended."
canonical: "https://signatureapi.com/docs/embedded/introduction"
source: "https://signatureapi.com/docs/embedded/introduction.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T12:39:46Z"
---

# Introduction

Let users sign inside your web or mobile app. Your server creates the ceremony, your app shows it in an iframe or WebView and reacts to how it ended.

_Last verified against API version 1.18.0._

![A signing ceremony embedded in a web app on a laptop and in a mobile app on a phone, each showing the document and a Start button](https://signatureapi.com/docs/images/embedded.webp)

Let your users sign documents directly in your web or mobile app using SignatureAPI's Embedded Signing.

You need both:

- A **server** to create an envelope and get a ceremony URL.
- A **client** to display the ceremony to the recipient.

## How it works

1. Your server creates the envelope. The recipient's ceremony uses `custom` or `email_code` authentication, so SignatureAPI returns the ceremony URL instead of emailing it.
2. Your server waits until the envelope is `in_progress`, then passes the URL to your app.
3. Your app appends `embedded=true` and an `event_delivery` value to the URL, and shows it in an iframe or a WebView.
4. When the ceremony ends, it sends your app an event: `ceremony.completed`, `ceremony.canceled`, `ceremony.declined` or `ceremony.failed`.
5. Your server confirms the outcome with the API or a webhook before it acts on it.

[Embedding in a Web Application](https://signatureapi.com/docs/embedded/web-app#create-the-envelope-on-your-server) shows every request of this flow, step by step.

## Server side

Your server holds the API key and creates the envelope with [Create Envelope](https://signatureapi.com/docs/api/resources/envelopes/create). Three settings on the recipient's `ceremony` matter for embedding:

- **`authentication`**: the first method must be `custom` (your app has already signed the user in) or `email_code` (SignatureAPI emails the user a code). With `email_link`, the default, SignatureAPI emails the link and returns no URL.
- **`embeddable_in`**: the origins of the pages that show the ceremony in an iframe, such as `https://app.acme.example`. SignatureAPI keeps it only when the first authentication method is `custom` or `email_code`. A native WebView that loads the ceremony as its own page doesn't need it.
- **`redirect_delay`**: how long the result page shows before the event, 3 seconds by default. Set `0` to show your own result screen right away.

The `201 Created` response already contains the URL in `recipients[].ceremony.url`. The ceremony opens once the envelope is `in_progress`; before that, it asks the recipient to try again later. Wait for the [`envelope.started`](https://signatureapi.com/docs/api/resources/events/envelope-events#envelopestarted) webhook, or read the envelope until its status is `in_progress`. To get a URL for an existing recipient, see [Ceremony URL](https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url).

Not sure which authentication method fits? Answer two questions:

**Which authentication method should my recipient use?**

- Who delivers the ceremony link to the recipient?
  - SignatureAPI, by email
    - Should the recipient also enter a code from their email before they see the documents?
      - No, the link is enough: **Email link (the default)**
      - Yes, add a second step: **Email link, then email code**
  - My application: my own email, SMS, an in-app link or an embedded ceremony
    - Has your application already authenticated the recipient?
      - Yes, they are signed in to my application
        - Do you also want a second factor that SignatureAPI controls?
          - No, my authentication is enough: **Custom**
          - Yes, add an email code: **Custom, then email code**
      - No, SignatureAPI should check their email: **Email code**

**Email link (the default).** SignatureAPI emails the recipient a direct link; opening it authenticates them. No setup: it is what you get when you leave out `ceremony`. The ceremony's `url` is `null` because SignatureAPI delivers it. See [Email link authentication](https://signatureapi.com/docs/api/resources/ceremonies/authentication/email-link).

```json
"ceremony": {
  "authentication": [{ "type": "email_link" }]
}
```

**Email link, then email code.** SignatureAPI emails the invitation link and, inside the ceremony, a 9-digit verification code, so your application sends neither email. The ceremony's `url` stays `null`. This is one of the two setups the HIPAA page describes for documents with protected health information. See [Multiple authentication methods](https://signatureapi.com/docs/api/resources/ceremonies/authentication/multiple), [HIPAA](https://signatureapi.com/docs/trust/compliance/hipaa).

```json
"ceremony": {
  "authentication": [
    { "type": "email_link" },
    { "type": "email_code" }
  ]
}
```

**Email code.** The API returns the ceremony URL and you deliver it through your own channel. When the recipient opens it, SignatureAPI emails them a 9-digit code to enter before signing. See [Email code authentication](https://signatureapi.com/docs/api/resources/ceremonies/authentication/email-code), [Ceremony URL](https://signatureapi.com/docs/api/resources/ceremonies/ceremony-url).

```json
"ceremony": {
  "authentication": [{ "type": "email_code" }]
}
```

**Custom.** Your application authenticates the recipient and SignatureAPI returns a ceremony URL to share or embed. Set `provider` and `data`: both appear in the audit log, and you must keep the records that prove how the recipient was authenticated. See [Custom authentication](https://signatureapi.com/docs/api/resources/ceremonies/authentication/custom).

```json
"ceremony": {
  "authentication": [
    {
      "type": "custom",
      "provider": "Your App",
      "data": { "session_id": "..." }
    }
  ]
}
```

**Custom, then email code.** Your application authenticates the recipient first, then SignatureAPI independently checks their email with a 9-digit code inside the ceremony. The URL is returned and your application delivers it. See [Multiple authentication methods](https://signatureapi.com/docs/api/resources/ceremonies/authentication/multiple).

```json
"ceremony": {
  "authentication": [
    { "type": "custom", "provider": "Your App", "data": { "session_id": "..." } },
    { "type": "email_code" }
  ]
}
```

## Client side

> **Warning:** Don't use our API directly from the client because API keys can be exposed. If someone gets your API key, they can access all your data in SignatureAPI.

After getting the ceremony URL, you can embed the signing interface directly into your application. You don't need any extra dependencies. Use standard components like **iframes** (for web apps), **WebView** (for Android), or **WKWebView** (for iOS).

Each platform catches the ceremony's result in its own way. A web page receives a JavaScript message; a native WebView intercepts a navigation to a `signatureapi-message://` URL:

```javascript Web
// URL: ...&embedded=true&event_delivery=message
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://sign.signatureapi.com') return;
  if (event.source !== iframe.contentWindow) return;
  handleCeremonyEvent(event.data.type, event.data.error_type);
});
```

```swift iOS
// URL: ...&embedded=true&event_delivery=redirect
func webView(_ webView: WKWebView, decidePolicyFor action: WKNavigationAction,
             decisionHandler: @escaping @MainActor (WKNavigationActionPolicy) -> Void) {
    guard let url = action.request.url, url.scheme == "signatureapi-message" else {
        return decisionHandler(.allow)
    }
    decisionHandler(.cancel)
    handleCeremonyEvent(url.host() ?? "")
}
```

```kotlin Android
// URL: ...&embedded=true&event_delivery=redirect
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
    val uri = request.url
    if (uri.scheme != "signatureapi-message") return false
    handleCeremonyEvent(uri.host.orEmpty())
    return true
}
```

```tsx React Native
// URL: ...&embedded=true&event_delivery=redirect
<WebView
  source={{ uri: ceremonyUrl }}
  originWhitelist={['*']}
  onShouldStartLoadWithRequest={(request) => {
    const match = /^signatureapi-message:\/\/([^/?#]+)/i.exec(request.url);
    if (!match) return true;
    handleCeremonyEvent(match[1]); // not new URL(): its host is empty here
    return false;
  }}
/>
```

```dart Flutter
// URL: ...&embedded=true&event_delivery=redirect
NavigationDelegate(
  onNavigationRequest: (request) {
    final uri = Uri.parse(request.url);
    if (uri.scheme != 'signatureapi-message') return NavigationDecision.navigate;
    handleCeremonyEvent(uri.host, uri.queryParameters['error_type']);
    return NavigationDecision.prevent;
  },
)
```

The event type, such as `ceremony.completed`, is the message's `type` or the URL's host. See [Ceremony Events](https://signatureapi.com/docs/embedded/ceremony-events) for every event and its data, then follow the guide for your platform.

### Web apps

- [Web Apps](https://signatureapi.com/docs/embedded/web-app): Embed the ceremony in a web application using HTML and JavaScript.

- [React](https://signatureapi.com/docs/embedded/frameworks/react): A reusable signing component with event handling and a redirect when the signer finishes.

- [Next.js](https://signatureapi.com/docs/embedded/frameworks/nextjs): A server action creates the ceremony; a client component shows it.

- [Vue and Nuxt](https://signatureapi.com/docs/embedded/frameworks/vue-nuxt): A Vue component and a Nuxt server route.

- [Angular](https://signatureapi.com/docs/embedded/frameworks/angular): A standalone component with signal inputs and outputs.

- [Svelte and SvelteKit](https://signatureapi.com/docs/embedded/frameworks/svelte): A Svelte 5 component and a SvelteKit form action.

### Mobile apps

- [iOS](https://signatureapi.com/docs/embedded/ios): Embed the ceremony in an iOS app using Swift and WKWebView.

- [Android](https://signatureapi.com/docs/embedded/android): Embed the ceremony in an Android app using Kotlin and WebView.

- [React Native](https://signatureapi.com/docs/embedded/react-native): Embed the ceremony in a React Native app.

- [Flutter](https://signatureapi.com/docs/embedded/flutter): Embed the ceremony in a Flutter app using webview\_flutter.

## Browser requirements

The ceremony runs in any modern browser or WebView. Default settings work, except that Android needs JavaScript turned on.

- JavaScript must be on.
- The ceremony uses no cookies, `localStorage`, `sessionStorage`, or IndexedDB. Third-party cookie blocking in WebKit is fine. On Android, DOM storage and third-party cookies can stay off.
- Allow the browser to contact these hosts:

| Host                     | Purpose                  |
| ------------------------ | ------------------------ |
| `sign.signatureapi.com`  | The ceremony             |
| `api.signatureapi.com`   | The ceremony's API calls |
| `vault.signatureapi.com` | Document page images     |
| `fonts.googleapis.com`   | Fonts                    |
| `fonts.gstatic.com`      | Fonts                    |

## Automated testing

To stop email link scanners from completing ceremonies, the ceremony arms completion only after input that a person produces. That input is a touch, a scroll-wheel turn, a key press, or a pointer moving across several positions. Until then, Finish opens a "Confirm to continue" dialog. This is expected.

Automated tests must produce real input:

- XCUITest taps on iOS.
- UiAutomator gestures on Android.
- Mouse movement in Playwright.

Clicks dispatched from JavaScript, such as Espresso-Web `webClick()`, don't count. Add a real gesture first, for example a swipe over the document. Don't confirm the dialog in tests: if it appears, the test isn't acting like a signer.

Assert on the ceremony event itself. In a desktop browser, the Navigation API fires a `navigate` event for the `signatureapi-message://` URL at the same moment a native WebView sees it. Listen for that event. Don't assert on the ceremony's console output.
