Embedded signing (v2)
Show the sajn signing page inside your own application, with an embed session that your server creates and the sajn embed SDK
Embedding v2 is in beta. Embed sessions and SDK 1.0 can change in ways that break your integration before the first stable release, estimated for November 2026. Embedding v1, described in Embedded signing, is stable.
In this guide, you embed the sajn signing page in your application, so a party signs without leaving it. Your server creates an embed session for one party of a sent document. Your page gives the session's client secret to the sajn embed SDK, and the SDK shows the signing page in an iframe.
This page describes SDK 1.0 and embed sessions. If you embed with SDK 0.x and the party's signing token, see Migrate from embed v1.
sajn has the following packages, all at version 1.0.0-beta.2 under the beta tag on npm. Pin the exact version: a later beta can break your integration.
@sajn/embed-js: a function 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.
How an embed session works
- The party opens a page in your application.
- The SDK calls your
fetchClientSecretfunction, which asks your server for a client secret. - Your server calls
POST /api/v1/embed-sessionswith your API key and returns theclientSecretfrom the response. - The SDK opens
https://app.sajn.se/embed/v2/{id}in an iframe and hands the client secret to the frame overpostMessage. The frame redeems the secret once. - The party signs in the frame, and the SDK calls your
onSignedcallback. - Your server confirms the signature with the
document.party.signedwebhook.
The session decides what the frame can do: its features, the pages that can show it, and its appearance. The browser can change only the cosmetic appearance and the language. The party's signing token never reaches the browser.
Before you begin
- Embedded signing is part of the Enterprise plan, and sajn turns it on for each organization. Being on Enterprise doesn't turn it on. To get started, contact hej@sajn.se. If you build on sajn to send documents to your own customers, you also need a partner license.
- A sandbox has embedded signing turned on when it's created, so you can build and test there first.
- Store an API key in the
SAJN_API_KEYenvironment variable on your server. The key needs write access to documents. Sessions need an API key: an OAuth app can't create them. To create a key, go to Inställningar > Utvecklare > API-nycklar (Settings > Developer > API keys) in the sajn app. - Send API version
2026-10in theSajn-Versionheader. The embed session endpoints don't exist in2026-09, which returns404 ROUTE_NOT_FOUNDfor them.
Add your embed domains
After sajn turns on embedding, the organization's developer settings get an Inbäddning (Embedding) tab. The domain list belongs to the organization, so every workspace in it shares the list.
- In the sajn app, go to Inställningar > Utvecklare > Inbäddning (Settings > Developer > Embedding).
- Enter each domain whose pages show the signing page, such as
app.example.com, and press Enter. - Click Spara ändringar (Save changes).
The list follows these rules:
*.example.commatches every subdomain ofexample.com, at any depth, but notexample.comitself. To allow both, add both. The same holds for embedding v1, which reads the same list.- Only pages served over HTTPS can show the frame.
localhostcan't be added. To test from your computer, expose your local app on a public HTTPS domain, such as through a tunnel, and add that domain. - An empty list allows no pages, and the API refuses to create sessions.
- sajn checks the list on every request, so removing a domain stops live sessions on it at once.
Embed the signing page
Create and send the document on your server
Create the document from a template, fill in the template's party and values, and send it, all in one request. Set the party's delivery to [], so sajn doesn't also email an invitation:
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": [
{ "templatePartyId": "TEMPLATE_PARTY_ID", "ref": "customer",
"name": "Alex Andersson", "email": "alex@example.com", "delivery": [] }
],
"fieldValues": [
{ "key": "monthly-fee", "value": "1 200 kr" }
],
"send": true
}'templatePartyIdis the ID of a party in the template'sparties, fromGET /api/v1/templates/TEMPLATE_ID. The document's copy of that party keeps its signature boxes and settings, and the details you send replace its own. WithouttemplatePartyId, the parties you send replace the template's parties and their signature boxes are removed.fieldValuesfills in values bykey, in the same shape asvaluesin Fill in values on a document. To list a template's keys, create a draft and callGET /api/v1/documents/DOCUMENT_ID/field-values.send: truesends the document after sajn creates it. You can create a session only for a sent document.
The response is the document with the status PENDING. Store its id, and the id of the party whose ref is customer in parties.
Create an embed session on your server
Add an endpoint to your server that your page calls. The endpoint checks who the user is, creates a session for that user's party, and returns only the clientSecret:
// POST /api/sajn/embed-session
app.post("/api/sajn/embed-session", requireSignedInUser, async (req, res) => {
// Replace with your own lookup of the document and party for this user.
const { documentId, partyId } = await findSigningForUser(req.user.id);
const response = await fetch("https://app.sajn.se/api/v1/embed-sessions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAJN_API_KEY}`,
"Sajn-Version": "2026-10",
"Content-Type": "application/json",
},
body: JSON.stringify({
documentId,
partyId,
origins: ["https://app.example.com"],
features: { rejection: true },
externalId: `user-${req.user.id}`,
}),
});
const session = await response.json();
if (!response.ok) {
console.error(session.code, session.message, session.requestId);
return res.status(502).json({ message: session.userMessage });
}
res.json({ clientSecret: session.clientSecret });
});The response looks like this:
{
"id": "emb_8f14e45fceea167a5a36dedd4bea2543",
"clientSecret": "emb_8f14e45fceea167a5a36dedd4bea2543_secret_Zk3pQ9vX2mT7bN1c",
"clientSecretExpiresAt": "2026-10-19T09:22:00.000Z",
"expiresAt": "2026-10-20T09:12:00.000Z",
"documentId": "cm4k2x9p10001abcd1234efgh",
"partyId": "cm4k2x9p20002abcd5678ijkl"
}The SDK calls your endpoint again each time a session ends, so create a new session on every call. Never cache a client secret, log it, or put it in a URL. The session id isn't a secret.
Show the signing page
In your page, give the SDK a container and a fetchClientSecret function that calls your endpoint:
import { createSigningEmbed } from "@sajn/embed-js";
const embed = createSigningEmbed({
container: document.querySelector("#signing"),
fetchClientSecret: async () => {
const response = await fetch("/api/sajn/embed-session", { method: "POST" });
if (!response.ok) throw new Error("Signing isn't available right now.");
const { clientSecret } = await response.json();
return clientSecret;
},
onSigned: ({ documentId }) => {
window.location.href = `/signed?doc=${documentId}`;
},
onError: ({ code, message }) => console.error(code, message),
});Give the container a height. For more information, see Size the frame. For React and Vue, see the framework pages.
Confirm the signature on your server
onSigned runs in the browser, so use it to update the screen, not as proof. Confirm the signature with the document.party.signed webhook event. The event means that this party's signature is recorded. To act on the sealed PDF, wait for document.completed.
Session lifetime
A session ends at the first of the following:
- The frame didn't redeem the client secret within 10 minutes of creation.
clientSecretExpiresAtin the response is this limit. - The frame had no activity for an hour. A frame in a hidden tab doesn't keep its session active.
- 24 hours passed since creation.
expiresAtin the response is this limit. - You revoked the session with
DELETE /api/v1/embed-sessions/{id}, which returns{ "id": "emb_…", "revoked": true }. - The API key that created the session was revoked or rotated.
When a session ends, the frame tells the SDK, and the SDK calls fetchClientSecret again for a new session. The party keeps their progress: a new session for a party who signed shows the signed state. If sessions end three times within one minute, the SDK stops and raises session_expired.
A session works only while the user who owns its API key can still read the document. If that user leaves the workspace or loses access to the document, the frame raises not_entitled.
Revoking a session doesn't stop the SDK from asking for a new one. To stop an embed for good, make your endpoint refuse the request, or call destroy() in the page.
Revoking a session also doesn't cancel an eID signing that the party already started in a new window. That signature is still recorded. To stop signing, withdraw the document, and confirm each signature with the document.party.signed webhook.
Create session request
POST /api/v1/embed-sessions takes the following body:
| Field | Type | Default | Description |
|---|---|---|---|
type | "signing" | "viewing" | "signing" | What the frame shows. viewing shows a sent or completed document to any party, read-only: the frame has no sign section, and the server refuses every signing action. |
documentId | string | Required | A sent document. |
partyId | string | Required | The party who signs in the frame. For signing, the party must sign the document, not only receive a copy. For viewing, any party. |
origins | string[] | Every embed domain | 1 to 10 pages that can show the frame, as bare origins such as https://app.example.com: the scheme, the host, and an optional port, with no path. Each must match one of the organization's embed domains. |
ancestorOrigins | string[] | None | Up to 10 more origins further up the frame chain, when your page is itself in a frame, such as inside a CRM. Each must match an embed domain. |
features | object | See Features | What the party can do besides signing. |
appearance | object | sajn's look | See Appearance. |
signatureInputModes | ("DRAW" | "TYPE" | "UPLOAD")[] | The workspace setting | How the party can create a drawn signature. This field can only remove modes that the workspace allows, never add one. |
locale | string | The document's language | The frame's language: sv, en, no, da, fi, de, is, es, fr, or it. |
externalId | string | The party's externalId | Your own reference, up to 255 characters. Every frame event carries it. |
bankIdReturnUrl | string | None | For a native app only: your app's URL scheme, such as myapp://signed, where the BankID app sends the party after signing with Swedish BankID on the same phone. An http or https URL returns 400 VALIDATION_FAILED. Without it, in a browser, the party switches back to your page from the BankID app. |
The endpoint returns the following errors, in addition to the common errors:
| Status and code | Cause |
|---|---|
400 VALIDATION_FAILED | The body is invalid, an origin isn't a bare HTTPS origin or doesn't match an embed domain, the organization has no embed domains, the document isn't sent, the party doesn't sign, bankIdReturnUrl is a web URL, or a color pair fails the contrast check. |
403 PERMISSION_DENIED | Embedded signing isn't turned on for the organization. |
404 NOT_FOUND | The document or the party doesn't exist in the workspace. |
Features
sajn enforces features on the server, so the browser can't turn them on. A feature that you leave out keeps its default.
| Feature | Default | Description |
|---|---|---|
rejection | false | The party can reject the document. |
delegation | false | The party can delegate signing to someone else. |
download | true | The party can download the document. |
Appearance
You can set appearance on the session and in the SDK. The SDK's values replace the session's values key by key, and colors merges color by color: an SDK colors object with only primary keeps the session's other colors. Custom CSS isn't supported.
| Key | Type | Default | Description |
|---|---|---|---|
colors | object | sajn's colors | Hex colors, such as #1f2937: background, foreground, muted, mutedForeground, primary, primaryForeground, border, and destructive. |
radius | number | sajn's radius | The corner radius in pixels, an integer from 0 to 24. |
fontFamily | "default" | "system" | "serif" | "default" | The font. |
colorScheme | "light" | "dark" | "system" | "light" | The color scheme. system follows the party's device. |
mode | "fixed" | "inline" | "fixed" | How the frame sizes itself. See Size the frame. |
header | boolean | true | If false, hides the bar with the document name. The menu for download, delegation, and rejection then sits in the frame's top corner. |
scrollIndicator | boolean | true | Shows a hint to scroll down, with a ring that fills as the party reads, until the sign section is in view. Only in fixed mode. |
documentId | boolean | true | Shows the document ID under the sign button. |
Text must stay readable, so sajn checks two color pairs for a contrast ratio of at least 4.5:1: foreground on background, and primaryForeground on primary. If colorScheme isn't dark and you set only one color of a pair, sajn checks it against its light default for the other color. A session request that fails the check returns 400 VALIDATION_FAILED. An SDK appearance that fails the check is ignored as a whole, and the frame keeps its current look.
The heading, the attestation, the instruction, and the sign button's wording are fixed, the same as on the hosted signing page. The consent text, the party's identity, the sign buttons, and the document itself keep their styles under any appearance.
Size the frame
The sign view is static: the document, and under it a sign section that is always visible. The frame shows no dialogs or overlays, so it works the same at any size.
fixed(default): the frame fills its container and scrolls inside. Give the container a height, at least 600px on phones. If the container has no height of its own, the SDK sets the frame tofallbackHeight, which is 600px by default.inline: the frame grows to the height of its content, and your page scrolls. Don't give the container a fixed height.
A document that requires the party to read it in full always uses fixed, because the read check needs a frame that scrolls.
Signing methods in the frame
Swedish BankID runs inside the frame, by QR code or on the same device. Click-to-sign and drawn signatures also run in the frame.
The providers of the following eIDs refuse to run inside a frame: MitID, Norwegian BankID, FTN, iDIN, and qualified electronic signatures (QES). For these, the frame opens the provider in a new window when the party clicks the sign button. The frame updates itself when the signature lands, even if the window doesn't report back. If the browser blocks the window, the button turns into a link to the same page.
If the party pays when they sign, the frame takes card payments only, including wallets such as Apple Pay and Google Pay. Payment methods that redirect, such as Klarna, aren't offered in the frame.
If the document has an access check (openVerification), the party passes it inside the frame before the document loads, the same as on the hosted page. Your application has usually signed the user in already, so consider leaving openVerification set to null for embedded documents. A party's own signVerification always applies before they sign.
Events
Events are hints for your page. They carry documentId, partyId, and externalId, never a credential. Confirm outcomes on your server with webhooks.
| JavaScript and React | Vue | When | Data |
|---|---|---|---|
onReady | @ready | The first page is on screen, and the party can act. | IDs, and loadMs: the time in milliseconds from the frame's navigation to the first page |
onSigned | @signed | The party signed. Also fires when the signature lands from a new window. | IDs |
onRejected | @rejected | The party rejected the document. Needs the rejection feature. | IDs and reasonGiven, a boolean. The reason text isn't sent to the browser. |
onFieldsSubmitted | @fields-submitted | The party submitted their form fields. No webhook matches this event. | IDs |
onFieldsProgress | @fields-progress | A required field was filled in or emptied. Use it for your own progress UI. | IDs, remaining (required fields still empty), and total (all the party's fields) |
onFieldsChanged | @fields-changed | The party stopped typing for half a second, or submitted. | IDs and values, every typed field's current value by its key. Values verified with an eID, such as a personnummer, are never sent. |
onVerified | @verified | The party passed the access check. | IDs |
onStateChange | @state-change | The frame connected, the signing state changed, or you called requestState(). | An EmbedState |
onResize | @resize | The content height changed. Only in inline mode. | The height in pixels |
onSessionExpired | @session-expired | The session ended. The SDK is fetching a new one. | None |
onError | @error | An error occurred. See Error codes. | code and message |
EmbedState has the following fields:
type EmbedState = {
revision: number; // Increases with every change
documentId: string;
partyId: string;
externalId: string | null;
documentStatus: string; // Such as "PENDING" or "COMPLETED"
partyStatus: "pending" | "signed" | "rejected";
fieldsSubmitted: boolean;
rejectionReasonGiven: boolean;
};Error codes
onError receives one of the following codes:
| Code | Raised by | Meaning |
|---|---|---|
session_not_found | Frame | The session doesn't exist. The SDK fetches a new session. |
session_expired | Frame or SDK | From the frame: the session ended, and the SDK fetches a new one. From the SDK: sessions ended three times within one minute, and the SDK stopped. |
session_revoked | Frame | The session was revoked, or its API key was revoked. The SDK fetches a new session. |
origin_not_allowed | Frame | The page's origin isn't in the session's origins or the organization's embed domains, or the frame URL was opened outside a frame. |
not_entitled | Frame | Embedded signing is off for the organization, the party used a feature that the session doesn't grant, or the user who owns the session's API key can no longer read the document. |
document_unavailable | Frame | The document can't be shown, such as because it was deleted or withdrawn. |
invalid_appearance | Frame | An appearance override from update() fails the contrast check together with the session's colors. The frame ignores the override and keeps the session's appearance. |
unsupported_sdk | Frame | The SDK version is no longer supported. Upgrade the package. |
bootstrap_timeout | SDK | fetchClientSecret didn't return, or the frame didn't answer, within bootstrapTimeoutMs, 10 seconds by default. See Troubleshooting. |
client_secret_failed | SDK | fetchClientSecret threw an error, or returned something that isn't a client secret. |
The frame retries a request that fails on the network or with a server error, and keeps showing the last state it loaded. If the document never loads, the frame shows a retry button. These failures don't reach onError, which gets only the codes in this table.
For session_not_found, session_expired, and session_revoked from the frame, onError runs first, then onSessionExpired, and then the SDK starts a new session. Don't show a final error for these codes. For invalid_appearance, the frame keeps working. For every other code, the frame shows its own message, and your page decides what to do next.
Troubleshooting
Fix a blank frame
The SDK raises bootstrap_timeout when the frame doesn't answer. Usually the browser refused to show the frame, and the frame stays blank. Open the browser console and look for a frame-ancestors or frame-src error. Then check the following causes:
- The page's origin isn't in the session's
origins. The origin must match exactly: the scheme, the host, and the port.https://www.example.comandhttps://example.comare different origins, and*.example.comdoesn't coverexample.com. If you leave outorigins, check the organization's embed domains instead. - Your page is inside another frame. Every page in the frame chain must be allowed. Add the outer pages' origins to
ancestorOrigins. - Your page's own Content Security Policy blocks the frame. If your page sends a
Content-Security-Policyheader, itsframe-srcorchild-srcmust allowhttps://app.sajn.se. - The page isn't served over HTTPS. The frame never loads in a page served over
http://. - The client secret is old. A secret from a session that ended more than 24 hours ago gets a refused frame. Create a new session on every
fetchClientSecretcall. - The
hostoption points at the wrong sajn host. Leavehostout to usehttps://app.sajn.se. Sandboxes use the same host. fetchClientSecretdoesn't return. The timeout also runs while your endpoint creates the session. Check that the endpoint responds, and how long it takes.- The network is slow, or something blocks the frame, such as a browser extension or a corporate proxy. To give a slow network more time, raise
bootstrapTimeoutMs.
Fix other problems
- The frame shows an error message: read the
codeinonErrorand see Error codes. - The frame is cut off or has no height: in
fixedmode, give the container a height. Ininlinemode, don't. - An eID window doesn't open: the browser blocked it. The party can use the link that the button turns into.
POST /api/v1/embed-sessionsfails: logcodeandrequestId, and see Errors.
Embed in a mobile app
In a React Native app, use @sajn/embed-react-native. It runs the signing page in a web view and opens eID pages and the BankID app for you. In Swift or Kotlin, the same guide shows how to wire a web view by hand.
If you'd rather not embed, show your page in the system browser: SFSafariViewController or ASWebAuthenticationSession on iOS, or Custom Tabs on Android. Every eID works there as on any web page.
Accessibility
The signing frame targets WCAG 2.2 level AA. sajn tests it with axe in light and dark mode: the signing view, form fields, the menu, the reject dialog, view mode, and the receipt after signing. The party can sign with the keyboard alone, and focus is always visible.
Your appearance settings take part in this. sajn rejects a text color and background pair below a 4.5:1 contrast ratio, both on the session and in update().
Security
- The party's signing token never reaches the browser. The frame redeems the client secret once and keeps a short-lived credential in memory.
- Only the pages in the session's
originsandancestorOriginscan show the frame, and only while they match the organization's embed domains. The page that talks to the frame must be inorigins. - Rotating or deleting the API key that created a session ends the session. The session also stops working when the key's user can no longer read the document.
- The SDK and the frame check the origin of every message, and post only to each other's origin.
- Features and origins can't change from the browser.
SDK changes
1.0.0-beta.2
This release breaks integrations built on 1.0.0-beta.1:
appearance.signIntroandappearance.labels.signButtonare removed. The heading, the attestation, the instruction, and the sign button's wording are fixed. The server ignores both keys if you still send them.features.commentsis removed. The server ignores it if you still send it.bankIdReturnUrlaccepts only an app's URL scheme, such asmyapp://signed. AnhttporhttpsURL returns400 VALIDATION_FAILED.
It also adds the following:
- The SDK and the frame agree on a protocol version when they connect, so a pinned SDK never gets events from a newer protocol.
- The SDK raises
bootstrap_timeoutwhenfetchClientSecretdoesn't return withinbootstrapTimeoutMs. - The React and Vue components take
bootstrapTimeoutMsandopenUrl, and exposerequestState().
Next steps
Was this page helpful?
Last updated on