---
title: "How to Embed Signing with createSigningUrl | TurboDocx"
description: "Generate an embedded signing URL with createSigningUrl: allow-list your domain, create the request, verify the signer, then mount the URL in an iframe."
url: "https://www.turbodocx.com/guides/embed-signing-with-createsigningurl"
---

# How to Embed Signing with createSigningUrl

> In five steps, you allow-list your domain, create an embedded request with `createEmbeddedSignature`, verify the signer, then call `createSigningUrl` to get a signing URL and mount it in an iframe, redirect, or new tab. No signing-request email is sent. The signer stays inside your product and is verified before the document opens.

Developer Guide by Amit Sharma (Software Engineer, Backend Architecture at TurboDocx). Published September 18, 2026. Updated October 7, 2026.

Quick install: [Agentic Quickstart Skill](https://www.turbodocx.com/quickstart.md), `npx skills add TurboDocx/quickstart`.

- **10 min** setup time
- **3 modes**: iframe, redirect, or new tab
- **5 min**: single-use link for external identity verification

Links: [GitHub SDK](https://github.com/TurboDocx/SDK/tree/main/packages/js-sdk) and [Identity Verification](https://www.turbodocx.com/electronic-signature-identity-verification.md).

## Key takeaways

- Add each https origin to the allow-list first. The signing page will not render in an iframe on any domain you have not added.
- No signing-link emails go out by default: createEmbeddedSignature sets sendEmail to false, so the signer only signs inside your app.
- Passcode and unverified signers get a reusable link that is valid until the document expires.
- Signers verified by your own identity provider get a single-use link that expires after 5 minutes, and minting a new one revokes the old one.

**SDK versions:** the method names below are the embedded-signing surface of the TurboDocx SDK. Confirm the exact parameters for your SDK version against the [SDK reference](https://docs.turbodocx.com/docs/SDKs/javascript).

## Step 1: Allow-list your embedding domain

Embedding is deny-by-default. The signing page refuses to render in an iframe until you add your app's exact `https` origin to your allowed embedding domains in your [embedded e-signature](https://www.turbodocx.com/embed-electronic-signature.md) settings. This is the clickjacking control, so nothing can frame the signer's screen without your say-so.

An organization admin opens Settings, Features and integrations, Configure E-Signature, selects Identity Verification, then the Identity & embedding tab, and adds the origin under Allowed embedding domains, pressing Enter after each one. Allowed embedding domains lives on the Identity & embedding tab of the E-Signature settings, alongside "Allow external identity verification" and "Allow identity verification override".

```text
https://app.yourcompany.com
```

**Local dev only:** you may add an `http://localhost` origin to test, but remove every `http://` origin and use `https` before production.

## Step 2: Create an embedded signature request

Call `createEmbeddedSignature` from your backend. Unlike `sendSignature`, it sends no signing-link email by default, and it returns a `recipientId` for each signer plus an `embedUrl` for whoever can sign now. Keep your API key on the server; it must never reach the browser.

```typescript
import { TurboSign } from '@turbodocx/sdk';
import { readFileSync } from 'fs';

TurboSign.configure({
  apiKey: process.env.TURBODOCX_API_KEY,
  orgId: process.env.TURBODOCX_ORG_ID,
  senderEmail: process.env.TURBODOCX_SENDER_EMAIL,
  senderName: process.env.TURBODOCX_SENDER_NAME,
});

// createEmbeddedSignature sends no signing-link email (sendEmail defaults to false).
const { documentId, recipients } = await TurboSign.createEmbeddedSignature({
  file: readFileSync('contract.pdf'),
  documentName: 'Order Form',
  recipients: [
    {
      name: 'John Doe',
      email: 'john@example.com',
      auth: { emailOtp: true }, // step 3: passcode before the document opens
      fields: { signature: '{signature1}', date: '{date1}' },
    },
  ],
});

const { recipientId, embedUrl, status } = recipients[0];
// status 'ready' means embedUrl is set and can be mounted now (step 5).
```

### Developer resources

- Drop the signing page into your app with the React widget:

  ```bash
  npm install @turbodocx/embed
  ```

  ```tsx
  import { TurboSignForm } from '@turbodocx/embed/react';

  <TurboSignForm embedUrl={embedUrl} origin={new URL(embedUrl).origin}
    onCompleted={({ documentId }) => markSigned(documentId)} />
  ```

- Complete embedded signing sample app: four working flows (the widget, your own iframe, external identity verification, and a kiosk). Clone it and run it locally. [View on GitHub](https://github.com/TurboDocx/SDK/tree/main/examples/embedded-web-app).
- Read the docs: [React widget](https://docs.turbodocx.com/docs/TurboSign/embedded-signing/react-widget), [Requesting a signing URL](https://docs.turbodocx.com/docs/TurboSign/embedded-signing/reference#requesting-a-signing-url).
- Packages: [@turbodocx/embed](https://www.npmjs.com/package/@turbodocx/embed), [@turbodocx/sdk](https://www.npmjs.com/package/@turbodocx/sdk).

## Step 3: Verify the signer

Choose how to confirm the signer. For a one-time passcode, set `auth` on the recipient: email or SMS. The signing page asks for the code before the document opens. Either way, the method is recorded on the certificate of completion. Compare every method under [e-signature identity verification](https://www.turbodocx.com/electronic-signature-identity-verification.md).

Passcodes are enabled on the One-time passcode tab of the E-Signature settings. With "Only when requested" selected, the passcode applies to the recipients whose request asks for it, such as an embedded request with auth set. SMS must be allowed there, with your SMS provider connected, before you use auth.sms.

```typescript
auth: { emailOtp: true }                         // email passcode
auth: { sms: { phoneNumber: '+13055551234' } }    // SMS passcode
// omit auth to use your organization's default channel
```

Already verify signers with your own identity provider? Create the recipient with `sendSignature`, `sendEmail: false`, and `identityVerification: { mode: 'external_idv', provider }`, then pass the assertion in step 4. The [bring your own identity verification](https://www.turbodocx.com/resources/bring-your-own-identity-verification-esignature.md) walkthrough covers every field and check.

## Step 4: Request a signing URL with createSigningUrl

Call `createSigningUrl` with the document id and recipient whenever you need a URL: the signer comes back later, it becomes the next signer's turn, or the signer is externally verified. What you get depends on how the signer is verified:

- **Passcode or no verification:** the signer's reusable `?token=` link. It stays valid until the document expires (`expiresAt` is the document's expiry, or null), and the passcode gate still applies.
- **External identity verification (or an admin-enabled override):** a single-use `?sut=` link that expires 5 minutes after it is issued. It opens once, and minting a new one revokes the previous link, so request it at the moment of signing.

```typescript
// Passcode or no verification: returns the reusable signing link.
const { url, expiresAt, pendingChecks } = await TurboSign.createSigningUrl(documentId, {
  recipientId,
  returnUrl: 'https://app.yourcompany.com/signed',
});
// pendingChecks: ['email_otp'] tells you the page will ask for a passcode.

// external_idv recipient: assert what your own identity provider verified.
// Returns a single-use URL that expires 5 minutes after issue.
const { url: verifiedUrl } = await TurboSign.createSigningUrl(documentId, {
  recipientId,
  identityAssertion: {
    provider: 'your-idv-vendor',          // must match the recipient's provider
    verificationId: idvResult.id,
    verifiedAt: idvResult.completedAt,    // ISO 8601
    subjectEmail: 'john@example.com',     // must match the recipient's email
  },
  returnUrl: 'https://app.yourcompany.com/signed',
});
```

## Step 5: Mount the signing URL

Send the URL to the browser and open it one of three ways. Use an iframe for a fully in-app experience, a redirect for the simplest integration, or a new tab when you want the signer to keep your app open behind them.

```tsx
// 1) Iframe: signer never leaves your app
<iframe src={url} title="Sign document" width="100%" height="800" />

// 2) Redirect: simplest
window.location.href = url;

// 3) New tab
window.open(url, '_blank', 'noopener');
```

What the signer sees: a passcode signer sees the "Verify your identity" gate first (with a masked email address and a Send Code button). After the passcode and consent, the signer fills their fields without leaving your app. Your app decides what happens on completion; the sample host swaps the frame for its own confirmation.

**Blank iframe?** The origin isn't allow-listed. Re-check step 1: the exact `https` origin hosting the iframe must be in your allowed embedding domains.

## Related

- [Identity Verification](https://www.turbodocx.com/electronic-signature-identity-verification.md): Verify signers before they sign. Email OTP, SMS OTP, and external identity provider verification, recorded on the certificate.
- [Embedded E-Signature](https://www.turbodocx.com/embed-electronic-signature.md): Embed white-label signing. The product overview of in-app signing, placement modes, and allowed embedding domains.
- [E-Signature API](https://www.turbodocx.com/e-signature-api.md): The full signing API surface.
- [API and SDK](https://www.turbodocx.com/products/api-and-sdk.md): SDKs across six languages.
- [Sign with TypeScript](https://www.turbodocx.com/guides/sign-documents-with-typescript.md): The typed send-for-signature guide.

## Frequently Asked Questions

### What is createSigningUrl?

It returns the URL that opens the TurboSign signing page for one recipient. For a passcode or unverified signer it is their reusable signing link, valid until the document expires, and the passcode gate still applies. For a signer verified by your own identity provider it is a single-use link that expires 5 minutes after it is issued. Mount it in an iframe, redirect to it, or open it in a new tab.

### Do I need to send a signing email to embed signing?

No. Create the request with createEmbeddedSignature, which defaults sendEmail to false and returns an embed URL for each signer whose turn it is, then call createSigningUrl whenever you need a fresh URL. The signer stays inside your application. TurboSign still emails passcodes to passcode signers and the completed copy when everyone has signed.

### How do I verify the signer's identity in an embedded flow?

Use an email passcode, an SMS passcode, or your own identity provider. Set auth on the recipient for a passcode. For your own provider, create the recipient with an external_idv identity mode and pass an identity assertion (provider, verification ID, time, and verified email) when you request the signing URL. The method used is recorded on the certificate of completion and the audit trail.

### Why is my embedded signing page blank?

Almost always, your app's origin is missing from the allow-list. The signing page is deny-by-default and will not load in an iframe until an admin adds your app's exact https origin to Allowed embedding domains in the E-Signature settings, on the Identity and embedding tab. Add the origin, including the scheme and any port, then reload the page that hosts the iframe.

## Start embedding signing today

Create a free account, allow-list your domain, and generate your first embedded signing URL in minutes.

[Get API Key Free](https://app.turbodocx.com)
