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

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.
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.
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 opensfields: { signature: '{signature1}', date: '{date1}' },},],});const { recipientId, embedUrl, status } = recipients[0];// status 'ready' means embedUrl is set and can be mounted now (step 5).
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.

auth: { emailOtp: true } // email passcodeauth: { 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.
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 (expiresAtis 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.
// 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 providerverificationId: idvResult.id,verifiedAt: idvResult.completedAt, // ISO 8601subjectEmail: 'john@example.com', // must match the recipient's email},returnUrl: 'https://app.yourcompany.com/signed',});
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.
// 1) Iframe: signer never leaves your app<iframe src={url} title="Sign document" width="100%" height="800" />// 2) Redirect: simplestwindow.location.href = url;// 3) New tabwindow.open(url, '_blank', 'noopener');



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.