Skip to Content
Embed sessions

Create an embed session

POST
/api/v1/embed-sessions

Start an embedded signing session for one party of a sent document, to show in your own page with the sajn embed SDK.

Flow:

  1. POST here from your server when the party opens your page.
  2. Return clientSecret to your page and hand it to the SDK, in fetchClientSecret.
  3. The SDK frames /embed/v2/{id} and the frame redeems the secret. The party signs in the frame.
  4. Confirm the outcome with the document.party.signed webhook. 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.

Authorization

headerAuthorizationBearer <token>

API key, e.g. Authorization: Bearer sajn_svc_.... Not scope-limited: acts with its owner's workspace role.

Header Parameters

Sajn-Version?string

API 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.

Value in"2026-09""2026-10"
Sajn-Workspace?string

ID 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?string

Makes 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.

Lengthlength <= 255

Request Body

Body

application/json
  1. body
type?string

What the frame shows. signing lets the party sign a sent document. viewing shows a sent or completed document to any party, read-only.

Default"signing"
Value in"signing""viewing"
documentId*string

A sent document.

Length1 <= length
partyId*string

The party who signs in the frame.

Length1 <= length
origins?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.

Items1 <= items <= 10
ancestorOrigins?array<>

Extra pages further up the frame chain, when your page is itself framed, such as inside a CRM.

Itemsitems <= 10
features?

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.

Itemsitems <= 3
locale?string

The frame's language. Defaults to the document's language.

Value in"sv""en""no""da""fi""de""is""es""fr""it"
externalId?string

Your own reference, returned on every frame event.

Lengthlength <= 255
bankIdReturnUrl?string

For 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.

Lengthlength <= 2048

Response Body

200

application/json
  1. response
id*string

The session id. Pass it to the SDK, or put it in the frame URL: it is not a secret.

clientSecret*string

Hand 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*string

When clientSecret expires if the frame hasn't redeemed it. Create a new session after this time.

Formatdate-time
expiresAt*string

When the session ends, at the latest. It also ends after an hour without activity.

Formatdate-time
documentId*string

The document ID.

partyId*string

The party ID.

Example Request
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"}'
Example Response
{  "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?