Developer Guide

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.

10 min

Setup time

3 modes

Iframe / redirect / tab

5 min

Single-use link for external IdV

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.

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

TurboDocx E-Signature Settings, Identity and embedding tab, showing Allow external identity verification, Allow identity verification override, and the Allowed embedding domains field where you add your https origin
Allowed embedding domains lives on the Identity & embedding tab of the E-Signature settings.
allowed origins (E-Signature settings)
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.

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.

create-embedded-request.ts
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).
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.

TurboDocx E-Signature Settings, One-time passcode tab, with Enable identity verification on, When to verify signers set to Only when requested, and Allow SMS as an alternative to email
Passcodes are enabled on the One-time passcode tab. 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 here, with your SMS provider connected, before you use auth.sms.
recipient auth options
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 walkthrough covers every field and check.

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.
create-signing-url.ts
// 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',
});
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.

mount.tsx (iframe / redirect / new tab)
// 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');
TurboSign signing page framed in a host app, showing the Verify your identity passcode gate with a masked email address and a Send Code button
A passcode signer sees the Verify your identity gate first. The code goes to their masked email address.
TurboSign signing page framed in a host app after the passcode check, with the Signature field highlighted and the date already filled
After the passcode and consent, the signer fills their fields without leaving your app.
Host app confirmation after signing: All set. Your policy is signed, with the completed copy emailed to the signer
Your app decides what happens on completion. This 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

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.