Create an embed session
Start an embedded signing session for one party of a sent document, to show in your own page with the sajn embed SDK.
Flow:
POSThere from your server when the party opens your page.- Return
clientSecretto your page and hand it to the SDK, infetchClientSecret. - The SDK frames
/embed/v2/{id}and the frame redeems the secret. The party signs in the frame. - Confirm the outcome with the
document.party.signedwebhook. Events in the browser are hints, not proof.
The session decides what the frame may do: features, appearance and origins can't be changed from the browser. A session lasts at most 24 hours, and ends after an hour without activity. When it ends, the SDK calls fetchClientSecret again, so keep that endpoint cheap.
Embedded signing is turned on per organization by sajn. Each origin must match one of the organization's embed domains. Create sessions with an API key: an OAuth app can't, because a session ends when the key that created it is rotated or deleted.
AuthorizationBearer <token>API key, e.g. Authorization: Bearer sajn_svc_.... Not scope-limited: acts with its owner's workspace role.
Sajn-Version?stringAPI version for this request. Without it, the request uses the organization's default version; an organization without a default is pinned to the latest version by its first request.
"2026-09""2026-10"Sajn-Workspace?stringID of the workspace this request acts in, from GET /api/v1/workspaces. Without it, an API key acts in its default workspace. The token's user must be a member of the workspace; an OAuth token only accepts the workspace it was granted for. A workspace that doesn't exist or can't be reached returns 403 WORKSPACE_ACCESS_DENIED.
Idempotency-Key?stringMakes retries safe. A retry with the same key and the same request replays the stored response for 24 hours (header Idempotent-Replayed: true); the same key with a different request returns 400.
length <= 255Body
application/json- body
type?stringWhat the frame shows. signing lets the party sign a sent document. viewing shows a sent or completed document to any party, read-only.
"signing""signing""viewing"documentId*stringA sent document.
1 <= lengthpartyId*stringThe party who signs in the frame.
1 <= lengthorigins?array<>The pages that may show the frame, such as https://app.example.com. Each must match one of your organization's embed domains. Leave it out to allow every embed domain.
1 <= items <= 10ancestorOrigins?array<>Extra pages further up the frame chain, when your page is itself framed, such as inside a CRM.
items <= 10features?What the party may do besides signing. Leave a feature out for its default.
appearance?signatureInputModes?array<>Narrows how the party can draw a signature. Your workspace setting is the ceiling.
items <= 3locale?stringThe frame's language. Defaults to the document's language.
"sv""en""no""da""fi""de""is""es""fr""it"externalId?stringYour own reference, returned on every frame event.
length <= 255bankIdReturnUrl?stringFor a native app only: your app's URL scheme, such as myapp://signed, where the BankID app sends the party after signing on the same phone. Web URLs are refused, because iOS opens them in a new tab. In a browser, the party switches back to the page from the BankID app.
length <= 2048200
application/json- response
id*stringThe session id. Pass it to the SDK, or put it in the frame URL: it is not a secret.
clientSecret*stringHand this to the SDK in the browser. The frame redeems it once, within 10 minutes. Never log it or put it in a URL.
clientSecretExpiresAt*stringWhen clientSecret expires if the frame hasn't redeemed it. Create a new session after this time.
date-timeexpiresAt*stringWhen the session ends, at the latest. It also ends after an hour without activity.
date-timedocumentId*stringThe document ID.
partyId*stringThe party ID.
curl -X POST 'https://app.sajn.se/api/v1/embed-sessions' \ -H 'Content-Type: application/json' \ -d '{ "type": "signing", "documentId": "cm4k2x9p10003abcd1234efgh", "partyId": "cm4k2x9p10004abcd1234efgh", "origins": [ "https://app.example.com" ], "features": { "rejection": true, "download": true }, "appearance": { "colors": { "primary": "#0f766e", "primaryForeground": "#ffffff" }, "radius": 8, "mode": "inline" }, "locale": "sv", "externalId": "EMP-0142"}'{ "id": "cm4k2x9p10003abcd1234efgh", "clientSecret": "Anställningsavtal – Kai Lindqvist", "clientSecretExpiresAt": "2026-09-28T09:12:00.000Z", "expiresAt": "2026-10-28T22:00:00.000Z", "documentId": "cm4k2x9p10003abcd1234efgh", "partyId": "cm4k2x9p10004abcd1234efgh"}Was this page helpful?