Session API
Start a BankID login and read the result with two REST calls — no OIDC library required
The REST alternative to OpenID Connect. Two calls: one to start a login, one to read the result. Same hosted page, same BankID engine, same claims — only the plumbing differs.
Use it when running an OIDC client is more trouble than it is worth. The typical case is a native mobile app: your server starts the login, the app opens the URL in an in-app browser, and a custom-scheme redirect drops the user straight back into the app.
To show the QR code and the BankID button in your own interface instead of sajn's hosted page, see Headless login.
Authenticated with your normal sajn API key, scoped login:write and login:read. See
Authentication.
1. Start a login
curl -X POST https://app.sajn.se/api/v1/login/sessions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"clientId": "YOUR_CLIENT_ID",
"redirectUri": "acme://auth",
"state": "your-internal-reference"
}'The response is the session, the same object that step 3 reads, with loginUrl and expiresAt
set:
{
"id": "kZ8f3cQpL7vR3mN8tYw4bZc1dH6jS0aEuGiKoPqTrUv",
"status": "PENDING",
"method": null,
"completedAt": null,
"state": "your-internal-reference",
"sub": null,
"claims": null,
"loginUrl": "https://login.sajn.se/l/kZ8f3cQpL7vR3mN8tYw4bZc1dH6jS0aEuGiKoPqTrUv",
"expiresAt": "2026-10-02T12:15:00.000Z"
}Later reads return loginUrl and expiresAt as null. The user must finish authenticating by
expiresAt, 15 minutes after the request.
redirectUri must be registered on the client. Custom schemes are supported so an in-app
browser can dismiss itself back into your app.
2. Send the user to loginUrl
Open it in a browser, in-app browser or web view. The user authenticates with BankID on sajn's hosted page.
When they finish, we redirect to your redirectUri:
acme://auth?sessionId=kZ8f3cQpL7vR3mN8tYw4bZc1dH6jS0aEuGiKoPqTrUv&state=your-internal-referenceThe redirect is only a handle — never treat it as proof of authentication. Anyone can craft that URL. The identity lives behind step 3, which is authenticated as your organization.
3. Read the result, from your server
curl https://app.sajn.se/api/v1/login/sessions/kZ8f3cQpL7vR3mN8tYw4bZc1dH6jS0aEuGiKoPqTrUv \
-H "Authorization: Bearer YOUR_API_KEY"{
"id": "kZ8f3cQpL7vR3mN8tYw4bZc1dH6jS0aEuGiKoPqTrUv",
"status": "COMPLETED",
"method": "SE_BANKID",
"completedAt": "2026-10-02T12:03:45.000Z",
"state": "your-internal-reference",
"sub": "clx7f2k9v0001abcdefghijkl",
"claims": {
"sub": "clx7f2k9v0001abcdefghijkl",
"amr": ["SE_BANKID"],
"auth_time": 1790942625,
"name": "Anna Andersson",
"given_name": "Anna",
"family_name": "Andersson",
"birthdate": "1985-03-15",
"nin": null,
"nin_type": null
},
"loginUrl": null,
"expiresAt": null
}sub and claims are null until status is COMPLETED. claims then has every claim key;
a claim your client isn't approved for is null, as nin and nin_type are in the preceding
example for a client without the nin scope. The projection is the same one the OIDC
id_token uses.
status | Meaning |
|---|---|
PENDING | In progress. This includes a cancelled or failed attempt that the user can still retry |
COMPLETED | Authenticated. Read claims |
FAILED | The login failed, and the user can't retry it in this session |
EXPIRED | BankID timed out, and the user can't retry it in this session |
In API version 2026-09, status is lowercase: pending, complete, failed, or expired, and method is BANKID_SE instead of SE_BANKID.
A completed result stays readable for 30 minutes, which is room for a retry or a brief outage on your side. After that it is gone; the authentication itself is still recorded for billing.
A session that has run out without completing, or that belongs to another workspace, returns
404 NOT_FOUND, not 403: "exists but isn't yours" is itself information. For every error
code, see Errors.
Handling the user who never comes back
The in-app browser case has a real failure mode: the user completes BankID, then closes the browser before the redirect fires. Your app never learns what happened.
Two ways to cover it:
Poll
GET the session every few seconds until it leaves PENDING. Stop at the expiresAt from
step 1. After that, the read returns 404.
The authentication completes on our side regardless — a background watchdog finishes the flow if the browser stops responding, so the result is there when you ask for it.
Differences from OIDC
| Session API | OIDC | |
|---|---|---|
| Starting a login | POST from your server | Browser redirect to /oidc/authorize |
| Credential | sajn API key | Client id + secret + PKCE |
| Result delivery | Authenticated GET | id_token from the token endpoint |
| Scopes | Everything the client is approved for | Requested per authorization request |
| Signature to verify | None — the API call is the trust boundary | Verify the id_token against JWKS |
Reference
Was this page helpful?
Last updated on