Iframe token

The iframe token is a one-time credential that authorizes loading the Subnoto signing UI for a specific envelope and signer. It has the prefix sit. and expires after 1 hour.

When you can create a token

You can only create an iframe token for a recipient whose verification type is set to email or SMS (i.e. 2FA is enabled for that recipient). If the recipient has verification type none, the API returns RECIPIENT_VERIFICATION_DISABLED. Set verification type when adding recipients (e.g. verificationType: "email" or "sms"). If a recipient was added via Smart Anchor detection, they usually have verificationType: "none" by default; call POST /public/envelope/update-recipient to set updates.verificationType to "email" or "sms" before creating an iframe token for them.

Creating the token

Call the API from your backend (never from the browser, so you do not expose your API keys). The endpoint is team-authenticated.

Request: POST /public/authentication/create-iframe-token

Body:

• workspaceUuid (string) - The workspace that owns the envelope
• envelopeUuid (string) - The envelope the signer will open
• signerEmail (string) - Email of the recipient; must match a recipient on the envelope (and that recipient must have verification type email or SMS)

Response: { iframeToken: string }

Example with the TypeScript SDK:

const { data, error } = await client.POST("/public/authentication/create-iframe-token", {
    body: {
        workspaceUuid,
        envelopeUuid,
        signerEmail: "[email protected]"
    }
});

if (error || !data?.iframeToken) {
    // handle error
    return;
}
// Pass data.iframeToken to your frontend

Using the token

Build the embed URL and pass it to your frontend. The path is /embeds/sign and the token goes in the hash:

• {embedBaseUrl}/embeds/sign#t={iframeToken}

If you omit the t= prefix, the embed also accepts #${iframeToken}. Default embed base URL is https://app.subnoto.com unless you use a custom embed domain.

Your frontend then either renders an iframe with this URL or uses a framework component that accepts the token (and optional host).

Security

Create the token only on the server. Do not send your API access key or secret to the client. The token is scoped to one envelope and one signer and expires after 1 hour; treat it as single-use.

Next steps

Get started

React

Vanilla / HTML