Skip to main content

Embedded Signing

Agent Skill

Let an agent scaffold this for you

Install the TurboDocx Quickstart Skill and let Claude Code, Cursor, Copilot, Codex, or any agent that speaks the Agent Skills standard install the SDK, wire it into your app, and write a working TurboSign integration end-to-end.

bash — turbodocx
$npx skills add TurboDocx/quickstart
# then, inside your agent:›/turbodocx-sdk turbosign
TurboDocx embedded signing sample app showing the signing panel inside a host web page
Complete embedded signing sample appFour working flows: widget, own iframe, external identity verification and kiosk. Clone it and run it locally.
View on GitHub →

Embedded signing takes a signer straight from your own UI to a TurboSign signing page, without signing-link emails. Your backend asks TurboSign for a signing URL when the signer is ready, and your app opens it in an iframe, a new tab, or a redirect.

At a glance:

  • Your signer never leaves your app. The signing page appears inside your product, and no signing-link email is needed.
  • Your API key stays on your server. The browser only ever sees a per-signer URL.
  • Each signer is verified your way. Use an email or SMS passcode, or your own identity verification vendor. The sender override skips verification while you test.
  • The signer's real email is the signer of record, and the verification lands on the certificate of completion and in the audit trail.
  • You get a completion event in the browser, and the completed webhook on your server.

How it works​

Every embedded signing integration makes the same four moves:

  1. Your app asks your server for a signing session. Your server creates the document and asks TurboDocx for a signing URL for one signer.
  2. The signing URL comes back to your app, which shows it, usually in an iframe.
  3. The signing page verifies the signer and collects the signature.
  4. The signing page tells your app it finished with a turbosign:completed message, and your server confirms the result.
How embedded signing worksStep 1: your app asks your server for a signing session, and your server, which holds the API key, asks TurboDocx to create the document and a signing URL. Step 2: the embed URL comes back through your server to your app, which loads it in an iframe. Step 3: the TurboSign signing page in the iframe verifies the signer and collects the signature. Step 4: the signing page posts a turbosign:completed message back to your app.Signing pageverifies, then signsYour appin the browserYour serverholds the API keyTurboDocxTurboSign API1POST /api/signing-sessioncreate document + URLembedUrl2embedUrliframe src3verify + sign4turbosign:completed
Your API key stays on your server. The browser only ever sees a per-signer signing URL.

Choose how signers verify​

Give every embedded signer a verification method. Your app shows the signing page itself and TurboSign emails no link, so a check is what ties the person at the screen to the signer of record.

TurboSign does not enforce this

If you set no verification on a signer and your organization verifies only when requested, TurboSign still issues a reusable signing link, and anyone holding it can sign. If your organization verifies on every signature request, the signer gets your organization's default method instead. See A recipient with no verification is unprotected.

MethodWho verifies the signerSigning URL
Email or SMS passcodeTurboSign sends a code before the document opensReusable for the life of the document
External identity verificationYour identity provider; your backend asserts the resultSingle-use, expires in about five minutes
Sender overrideNobody (testing only, marked not identity-verified)Single-use, expires in about five minutes

The Identity verification section compares them in full, including which ones also work for signers you email.

Choose your path​

You want to...Signer verifies withFront endGuide
Write the least code in a React appEmail passcodeThe React TurboSignForm componentReact widget
Keep full control of the iframe, in any frameworkEmail passcodeYour own iframe and message listenerYour own iframe
Use Vue, Angular, Svelte or plain HTMLEmail passcodeThe turbosign-form web componentWeb component
Have two or more people sign in order on one deviceAn email passcode eachAnyKiosk signing (two signers, one device)
Verify signers by text messageSMS passcodeAnyPasscodes in embedded signing
Reuse a check your identity vendor already ranYour identity providerAnyExternal identity verification
Try the flow in development without verificationNothing (marked not identity-verified)AnySender override for testing
Not sure? Start with the React widget or the web component

They check the message origin and surface the completion event for you. Choose your own iframe only when you need full control of the frame.

Before you start​

You need these in place before any guide works:

  1. An admin has turned on embedded signing. In Settings > Features and integrations > Signatures card > Configure E-Signature > Identity Verification, the Enable identity verification switch is on. Despite its name, it is the master switch for embedded signing and every verification mode.
  2. Your app's origin is allowed. On the Identity & embedding tab, your origin (for example https://app.yourcompany.com) is under Allowed embedding domains.
  3. You have an API key with the right role: an Administrator or Contributor key.
  4. Your PDF has text anchors where fields go, for example {signature1} and {date1}.
  5. The TurboDocx SDK is installed on your server. See the TurboSign SDK for your language.

Set up your organization walks an admin through steps 1 and 2 with screenshots.

The signing page will not appear until your origin is allowed

Embedding is denied by default. Until an admin adds your app's origin under Allowed embedding domains, the iframe stays blank. That is the clickjacking protection working, not a bug.

User-role API keys are rejected

Requesting a signing URL needs an Administrator or Contributor key. A User-role key can create the document, but the signing URL request fails with HTTP 403.

localhost is for development only

You can allow http://localhost origins to test on your machine. Remove every http:// origin before you go live; production origins must be https://.

The flow, end to end​

  1. Your backend prepares the document with an embedded recipient and sendEmail: false, then stores the returned documentId on the customer record.
  2. Your app shows a "Sign now" button. Clicking it calls your backend, not a stored link.
  3. Your backend confirms the signed-in user matches the customer record, calls createSigningUrl, and returns the URL.
  4. The signing page verifies the signer (a passcode, the asserted external verification, or nothing for override) and shows the document.
  5. The signer signs. The page posts turbosign:completed, and TurboSign returns the signer to your returnUrl if you set one.
  6. The completed webhook updates your record. Download the signed PDF; the certificate shows the identity-verification line.

The API reference has every request and response field.

Common errors​

HTTPcodeWhat to do
(blank iframe)noneAdd your exact origin under Allowed embedding domains.
403none (a plain 403 Forbidden)The API key belongs to a User. Use an Administrator or Contributor key.
403EmbeddedSigningNotEnabledAsk an admin to turn on Enable identity verification.
403OtpOverrideNotAllowedYour organization locked the passcode method. Omit the channel, or ask an admin to let senders change it.
409RecipientNotInTurnAn earlier signer has not finished. Mint this signer's URL when it is their turn.
410SigningUrlNotRedeemableA single-use URL was used or expired. Request a new one.

Every error code is in the API reference.

Good practice​

  • Never store a signing URL. Request one when the signer clicks. Passcode signers get a reusable link that lasts as long as the document; external identity verification and override signers get a single-use link that expires after about five minutes.
  • Verify the signer in your own app first. Confirm the logged-in user is the recipient before you request a URL.
  • Use externalId to reference a signer by your own record (an Airtable row, a CRM contact) instead of storing TurboDocx's recipient id.
  • Set allowed embedding domains before you iframe the signing page.
  • Confirm completion on your server. Treat the browser event as a hint, and rely on the document status or the completed webhook.

Next​

Set up your organization, then pick a guide from Choose your path.