Embedded signing
Show the sajn signing page inside your own application in an iframe, with your own theme
In this guide, you embed the sajn signing page in your application, so a party signs without leaving it. Your server creates the document and gets the party's signing token, and your frontend shows the signing page in an iframe through one of the sajn embedding packages.
This page describes embedding v1, which is stable. Embedding v2, with embed sessions and SDK 1.0, is in beta: see Embedded signing (v2).
sajn has the following packages:
@sajn/embed-js: a function API and a Web Component for any web page. See JavaScript.@sajn/embed-react: a React component for React 18 and later. See React.@sajn/embed-vue: a Vue component for Vue 3.3 and later. See Vue.
Before you begin
- Embedded signing is part of the Enterprise plan. If you build on sajn to send documents to your own customers, you also need a partner license. To get started, contact hej@sajn.se.
- Store your API key in the
SAJN_API_KEYenvironment variable on your server. To create a key, go to workspace settings in the sajn app, then Utvecklare (Developer) > API-nycklar (API keys).
Turn on embedding
After sajn turns on embedding for your organization, add the domains that can embed the signing page:
- In the sajn app, go to workspace settings, then Utvecklare (Developer) > Inbäddning (Embedding).
- Enter your domains, separated by commas. A domain can start with a wildcard, such as
*.example.com.
The list starts empty, and an empty list allows no domains outside sajn. The list accepts only public domains served over HTTPS, so localhost doesn't work. To test from your computer, expose your local app on a public HTTPS domain, such as through a tunnel, and add that domain. To test before you go live, use the sandbox.
Embed the signing page
Create the document on your server
Create the document with the party's delivery set to [], so sajn doesn't also email an invitation, and send it:
curl -X POST https://app.sajn.se/api/v1/documents \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{
"name": "Service agreement",
"templateId": "TEMPLATE_ID",
"parties": [
{ "name": "Alex Andersson", "email": "alex@example.com", "role": "SIGNER", "delivery": [] }
]
}'
curl -X POST https://app.sajn.se/api/v1/documents/DOCUMENT_ID/send \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10" \
-H "Content-Type: application/json" \
-d '{}'The first request returns the document. Replace DOCUMENT_ID with its id, and note the party's id in parties.
Get the party's token on your server
curl https://app.sajn.se/api/v1/documents/DOCUMENT_ID/parties/PARTY_ID \
-H "Authorization: Bearer $SAJN_API_KEY" \
-H "Sajn-Version: 2026-10"Replace PARTY_ID with the party's id. The response has the party's signingUrl, such as https://app.sajn.se/sign/DOCUMENT_ID?token=PARTY_TOKEN. Read the token from its token query parameter:
const token = new URL(party.signingUrl).searchParams.get("token");sajn records every read of the signing URL in the document's audit log. Store the token with the document, and reuse it instead of reading the party on every page load. Return the token and the document ID to your frontend. The token lets anyone sign as the party, so give it only to that person's session.
Show the signing page
In your frontend, pass the document ID and the token to the embed:
import { embedSignDocument } from "@sajn/embed-js";
embedSignDocument({
element: "#signing",
documentId: "DOCUMENT_ID",
token: "PARTY_TOKEN",
language: "en",
onSignerCompleted: ({ documentId }) => {
window.location.href = `/signed?doc=${documentId}`;
},
});Replace PARTY_TOKEN with the token from the previous step. For React and Vue, see the framework pages.
Confirm the signature on your server
The signer-completed event runs in the browser, so treat it as a signal to update the screen, not as proof. Confirm the signature with the document.party.signed or document.completed webhook event.
Options
Every package takes the same options. The JavaScript package uses the names shown; the React package uses the same names as props, and the Vue package uses kebab-case attributes, such as document-id.
| Option | Type | Default | Description |
|---|---|---|---|
documentId | string | Required | The document ID. |
token | string | Required | The party's token, from the token query parameter of its signingUrl. |
host | string | https://app.sajn.se | The sajn host. |
language | string | en | The language of the signing page: sv, en, no, da, fi, de, is, es, fr, or it. |
className | string | None | A CSS class for the iframe. |
allowDocumentRejection | boolean | false | If true, the party can reject the document. |
showScrollIndicator | boolean | true | If true, shows a scroll indicator. |
signatureInputModes | ('draw' | 'type' | 'upload')[] | All | How the party can create a drawn signature. This option can only remove modes that the workspace allows, never add one. |
showDocumentId | boolean | true | If true, shows the document ID under the sign button. |
cssVars | object | None | Theme colors, described in the following section. |
additionalProps | Record<string, string | number | boolean> | None | More options passed to the embed. |
Theme colors
cssVars takes the following colors:
type CssVars = {
background?: string; // Page background
primary?: string; // Buttons and accents
foreground?: string; // Main text
mutedForeground?: string; // Secondary text
};Events
Every package emits the following events:
document-ready: the iframe loaded. No data.signer-completed: the party finished signing. Data:token,documentId,signerId(the party ID), andfailed, a reason, when signing failed.variables-submitted: the party submitted their form fields. The document isn't signed yet: signing opens when every party with form fields has submitted. Data:token,documentId, andsignerId.signer-rejected: the party rejected the document, which needsallowDocumentRejection. Data:token,documentId,signerId, andreason.document-error: an error occurred. Data:codeandmessage.
In the event data, signerId is the party's id; the embed packages keep this name.
Security
- Only domains in the workspace's allowlist can embed the signing page.
- The token is checked on the server before the page renders.
- If the party verifies with an eID or a camera-based check, the iframe needs the
allow="camera"attribute. - If the document has
openVerification, the party passes that check inside the iframe before any content loads, the same as on the hosted page. Your application has usually signed the user in already, so consider leavingopenVerificationset tonullfor embedded documents. A party's ownsignVerificationalways applies before they sign.
Handle errors
- A
document-errorevent: readcode. A missing or invalid token, or a domain that isn't in the allowlist, stops the page from loading. - A blank iframe: check that your domain is in the allowlist and is served over HTTPS.
For errors from the REST API calls on your server, see Errors.
Next steps
To see an embed working, open the live demo, and read its source code on GitHub.
Was this page helpful?
Last updated on