Skip to Content

Headless login

Show the BankID QR code and button in your own interface while sajn talks to BankID

Headless login runs the authentication in your interface instead of sajn's hosted page. You show the QR code and the button that opens the BankID app. Your server starts the attempt, polls it, and reads the result. sajn talks to BankID.

Headless login needs a client that uses your own BankID certificate, so the BankID app shows your company name. Clients in a sandbox organization run against the BankID mock instead. The calls use your sajn API key with the login:write and login:read scopes.

1. Create a session

Create the session as in the Session API. Keep the id. Headless login doesn't use loginUrl.

2. Start an attempt

Call this from your server when the user chooses to log in. Send the user's IP address as your server sees it, never your server's own address.

curl -X POST https://app.sajn.se/api/v1/login/sessions/SESSION_ID/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "SE_BANKID",
    "endUserIp": "203.0.113.24",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) …",
    "returnUrl": "https://acme.se/logga-in"
  }'
Response
{
  "id": "kZ8f3cQpL7vR3mN8tYw4bZc1dH6jS0aEuGiKoPqTrUv",
  "method": "SE_BANKID",
  "qrCode": "bankid.67df3917-fa0d-44e5-b327-edcc928297f8.0.dd5bb5f5…",
  "autoStartToken": "7c40b5c9-fa74-49cf-b98c-bfe651f9a7c6",
  "autoStartUrl": "https://app.bankid.com/?autostarttoken=7c40b5c9-fa74-49cf-b98c-bfe651f9a7c6&redirect=https%3A%2F%2Facme.se%2Flogga-in",
  "expiresAt": "2026-11-08T10:18:12.002Z"
}
FieldUse
methodThe eID. Leave it out when the client allows one method.
userAgentOptional. It improves BankID's risk check, and autoStartUrl uses it to return the user to the right browser.
returnUrlOptional. Where the BankID app sends a user on the same device. It must be registered on the client. Without it, the user switches back by hand.

3. Show the QR code or the button

  • Another device: render qrCode as a QR code. It changes every second, so show the new value from each poll.
  • The same device: open autoStartUrl from a tap. iOS blocks an app switch that no tap started. To build your own link, use autoStartToken.

4. Poll until the attempt ends

Poll every 1 to 2 seconds and show the new qrCode while status is PENDING.

curl -X POST https://app.sajn.se/api/v1/login/sessions/SESSION_ID/poll \
  -H "Authorization: Bearer YOUR_API_KEY"
Pending
{
  "id": "kZ8f3cQpL7vR3mN8tYw4bZc1dH6jS0aEuGiKoPqTrUv",
  "status": "PENDING",
  "hintCode": "outstandingTransaction",
  "qrCode": "bankid.67df3917-fa0d-44e5-b327-edcc928297f8.6.4a1f0c2e…",
  "attemptsRemaining": 4
}
statusWhat to do
PENDINGKeep polling. Use hintCode to tell the user what to do, for example userSign while they confirm in the app.
COMPLETEDRead the result in step 5.
FAILEDShow why, from hintCode. To retry, start a new attempt while attemptsRemaining is above 0.
EXPIREDThe user didn't finish in time. Start a new attempt while attemptsRemaining is above 0.

Stop polling when status leaves PENDING, or when the user leaves the page. After the session runs out, a poll returns 404 NOT_FOUND, so stop then too.

The login completes even if you stop polling, and login.completed fires. Calling start again while an attempt runs returns that attempt with its current qrCode.

5. Read the result

When status is COMPLETED, read the claims with GET /api/v1/login/sessions/{id}. The poll response carries no identity. The authenticated read is the only place your server learns who logged in.

Cancel an attempt

When the user presses Cancel, cancel the attempt so the BankID app stops waiting:

curl -X POST https://app.sajn.se/api/v1/login/sessions/SESSION_ID/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

The response has the same shape as a poll. The session stays open, so the user can start a new attempt. If the user finished in the BankID app just before the cancel, status is COMPLETED.

Errors

CodeWhen
VALIDATION_FAILEDendUserIp isn't an IP address, or method isn't an eID the API knows.
INVALID_REQUESTThe client doesn't allow method, or returnUrl isn't registered on the client.
INVALID_STATEYou polled before starting an attempt, or started one after the login completed.
FORBIDDENThe client uses sajn's certificate, not your own.
NOT_FOUNDThe session ran out, belongs to another workspace, or was started through OIDC.
TOO_MANY_REQUESTSThe session used all its attempts, or too many logins started from one IP address.

Reference

Start

POST …/start

Poll

POST …/poll

Cancel

POST …/cancel

Was this page helpful?

Last updated on