Create an embed session

curl --request POST \
  --url https://app.sajn.se/api/v1/embed-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}
'

import requests

url = "https://app.sajn.se/api/v1/embed-sessions"

payload = {
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://app.sajn.se/api/v1/embed-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.sajn.se/api/v1/embed-sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.sajn.se/api/v1/embed-sessions"

	payload := strings.NewReader("{\n  \"type\": \"signing\",\n  \"documentId\": \"cm4k2x9p10003abcd1234efgh\",\n  \"partyId\": \"cm4k2x9p10004abcd1234efgh\",\n  \"origins\": [\n    \"https://app.example.com\"\n  ],\n  \"features\": {\n    \"rejection\": true,\n    \"download\": true\n  },\n  \"appearance\": {\n    \"colors\": {\n      \"primary\": \"#0f766e\",\n      \"primaryForeground\": \"#ffffff\"\n    },\n    \"radius\": 8,\n    \"mode\": \"inline\"\n  },\n  \"locale\": \"sv\",\n  \"externalId\": \"EMP-0142\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.sajn.se/api/v1/embed-sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"signing\",\n  \"documentId\": \"cm4k2x9p10003abcd1234efgh\",\n  \"partyId\": \"cm4k2x9p10004abcd1234efgh\",\n  \"origins\": [\n    \"https://app.example.com\"\n  ],\n  \"features\": {\n    \"rejection\": true,\n    \"download\": true\n  },\n  \"appearance\": {\n    \"colors\": {\n      \"primary\": \"#0f766e\",\n      \"primaryForeground\": \"#ffffff\"\n    },\n    \"radius\": 8,\n    \"mode\": \"inline\"\n  },\n  \"locale\": \"sv\",\n  \"externalId\": \"EMP-0142\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.sajn.se/api/v1/embed-sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"signing\",\n  \"documentId\": \"cm4k2x9p10003abcd1234efgh\",\n  \"partyId\": \"cm4k2x9p10004abcd1234efgh\",\n  \"origins\": [\n    \"https://app.example.com\"\n  ],\n  \"features\": {\n    \"rejection\": true,\n    \"download\": true\n  },\n  \"appearance\": {\n    \"colors\": {\n      \"primary\": \"#0f766e\",\n      \"primaryForeground\": \"#ffffff\"\n    },\n    \"radius\": 8,\n    \"mode\": \"inline\"\n  },\n  \"locale\": \"sv\",\n  \"externalId\": \"EMP-0142\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "code": "VALIDATION_FAILED",
  "message": "Invalid input: expected string, received undefined",
  "userMessage": "Förfrågan innehåller ogiltiga värden.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "issues": [
    {
      "path": "documentId",
      "code": "INVALID_TYPE",
      "message": "Invalid input: expected string, received undefined"
    }
  ]
}

{
  "code": "UNAUTHORIZED",
  "message": "Invalid API token",
  "userMessage": "Ogiltig API-nyckel",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "Insufficient OAuth scope: requires documents:write",
  "userMessage": "Applikationen saknar behörighet (scope) för denna åtgärd.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "requiredScopes": [
    "documents:write"
  ],
  "grantedScopes": [
    "profile:read"
  ]
}

{
  "code": "NOT_FOUND",
  "message": "Document not found",
  "userMessage": "Resursen hittades inte.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "resource": "document"
}

{
  "code": "INVALID_STATE",
  "message": "The resource's current state doesn't allow the operation, such as editing a document that was already sent or downloading a file that isn't produced yet.",
  "userMessage": "Åtgärden är inte möjlig i resursens nuvarande status.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "RATE_LIMITED",
  "message": "API rate limit exceeded",
  "userMessage": "För många förfrågningar. Försök igen om en stund.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "INTERNAL_ERROR",
  "message": "Internal server error",
  "userMessage": "Något gick fel.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "UPSTREAM_UNAVAILABLE",
  "message": "A service the operation depends on, such as an eID provider or a connected integration, failed or is unavailable. Retry with exponential backoff.",
  "userMessage": "En extern tjänst svarar inte just nu. Försök igen om en stund.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Embed sessions

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:

POST here from your server when the party opens your page.
Return clientSecret to your page and hand it to the SDK, in fetchClientSecret.
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.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.

POST

api

embed-sessions

Create an embed session

curl --request POST \
  --url https://app.sajn.se/api/v1/embed-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}
'

import requests

url = "https://app.sajn.se/api/v1/embed-sessions"

payload = {
    "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"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
  })
};

fetch('https://app.sajn.se/api/v1/embed-sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.sajn.se/api/v1/embed-sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.sajn.se/api/v1/embed-sessions"

	payload := strings.NewReader("{\n  \"type\": \"signing\",\n  \"documentId\": \"cm4k2x9p10003abcd1234efgh\",\n  \"partyId\": \"cm4k2x9p10004abcd1234efgh\",\n  \"origins\": [\n    \"https://app.example.com\"\n  ],\n  \"features\": {\n    \"rejection\": true,\n    \"download\": true\n  },\n  \"appearance\": {\n    \"colors\": {\n      \"primary\": \"#0f766e\",\n      \"primaryForeground\": \"#ffffff\"\n    },\n    \"radius\": 8,\n    \"mode\": \"inline\"\n  },\n  \"locale\": \"sv\",\n  \"externalId\": \"EMP-0142\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.sajn.se/api/v1/embed-sessions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"signing\",\n  \"documentId\": \"cm4k2x9p10003abcd1234efgh\",\n  \"partyId\": \"cm4k2x9p10004abcd1234efgh\",\n  \"origins\": [\n    \"https://app.example.com\"\n  ],\n  \"features\": {\n    \"rejection\": true,\n    \"download\": true\n  },\n  \"appearance\": {\n    \"colors\": {\n      \"primary\": \"#0f766e\",\n      \"primaryForeground\": \"#ffffff\"\n    },\n    \"radius\": 8,\n    \"mode\": \"inline\"\n  },\n  \"locale\": \"sv\",\n  \"externalId\": \"EMP-0142\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.sajn.se/api/v1/embed-sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"signing\",\n  \"documentId\": \"cm4k2x9p10003abcd1234efgh\",\n  \"partyId\": \"cm4k2x9p10004abcd1234efgh\",\n  \"origins\": [\n    \"https://app.example.com\"\n  ],\n  \"features\": {\n    \"rejection\": true,\n    \"download\": true\n  },\n  \"appearance\": {\n    \"colors\": {\n      \"primary\": \"#0f766e\",\n      \"primaryForeground\": \"#ffffff\"\n    },\n    \"radius\": 8,\n    \"mode\": \"inline\"\n  },\n  \"locale\": \"sv\",\n  \"externalId\": \"EMP-0142\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "code": "VALIDATION_FAILED",
  "message": "Invalid input: expected string, received undefined",
  "userMessage": "Förfrågan innehåller ogiltiga värden.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "issues": [
    {
      "path": "documentId",
      "code": "INVALID_TYPE",
      "message": "Invalid input: expected string, received undefined"
    }
  ]
}

{
  "code": "UNAUTHORIZED",
  "message": "Invalid API token",
  "userMessage": "Ogiltig API-nyckel",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "Insufficient OAuth scope: requires documents:write",
  "userMessage": "Applikationen saknar behörighet (scope) för denna åtgärd.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "requiredScopes": [
    "documents:write"
  ],
  "grantedScopes": [
    "profile:read"
  ]
}

{
  "code": "NOT_FOUND",
  "message": "Document not found",
  "userMessage": "Resursen hittades inte.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2",
  "resource": "document"
}

{
  "code": "INVALID_STATE",
  "message": "The resource's current state doesn't allow the operation, such as editing a document that was already sent or downloading a file that isn't produced yet.",
  "userMessage": "Åtgärden är inte möjlig i resursens nuvarande status.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "RATE_LIMITED",
  "message": "API rate limit exceeded",
  "userMessage": "För många förfrågningar. Försök igen om en stund.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "INTERNAL_ERROR",
  "message": "Internal server error",
  "userMessage": "Något gick fel.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

{
  "code": "UPSTREAM_UNAVAILABLE",
  "message": "A service the operation depends on, such as an eID provider or a connected integration, failed or is unavailable. Retry with exponential backoff.",
  "userMessage": "En extern tjänst svarar inte just nu. Försök igen om en stund.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Embedding v2 is in beta, and this endpoint can change in ways that break your integration before its first stable release, estimated for November 2026. See Embedding v2.

Authorizations

Authorization

string

header

required

Personal API key, e.g. Authorization: Bearer sajn_sk_.... Not scope-limited — acts as the issuing user.

Headers

Sajn-Version

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

Available options:

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.

Maximum string length: 255

Body

application/json

Body

documentId

string

required

A sent document.

Minimum string length: 1

partyId

string

required

The party who signs in the frame.

Minimum string length: 1

type

enum<string>

default:signing

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

Available options:

signing,

viewing

origins

string[]

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.

Required array length: 1 - 10 elements

Required string length: 1 - 512

ancestorOrigins

string[]

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

Maximum array length: 10

Required string length: 1 - 512

features

object

What the party may do besides signing. Leave a feature out for its default.

Show child attributes

appearance

object

Show child attributes

signatureInputModes

enum<string>[]

Narrows how the party can draw a signature. Your workspace setting is the ceiling.

Maximum array length: 3

Available options:

DRAW,

TYPE,

UPLOAD

locale

enum<string>

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

Available options:

sv,

en,

no,

da,

fi,

de,

is,

es,

fr,

it

externalId

string

Your own reference, returned on every frame event.

Maximum string length: 255

bankIdReturnUrl

string

Where the BankID app sends the party after signing on the same phone. An https URL on one of your embed domains, or your native app's URL scheme, such as myapp://signed. Leave it out and the BankID app returns the party to the browser they came from.

Maximum string length: 2048

Response

200

string

required

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

clientSecret

string

required

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<date-time>

required

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

expiresAt

string<date-time>

required

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

documentId

string

required

The document ID.

partyId

string

required

The party ID.

Get started

Core concepts

Guides

Webhooks

API fundamentals

Upgrading

sajn Login

API reference

Create an embed session

Authorizations

Headers

Body

Response