Identity Verification
Use the identity endpoints to start a user authentication flow with a supported identity provider (MitID, BankID, eIDAS) and retrieve normalized identity data once the user has authenticated.
Flow overview
1. POST /api/auth/{brokerId}/start → receive sessionId + redirectUrl
2. Redirect user to redirectUrl
3. User authenticates at the identity provider
4. Provider redirects back to your returnUrl (status=success|failed|cancelled)
5. POST /api/auth/{brokerId}/result → receive normalized identity data
Start identification — `POST /api/auth/
Initiates an authentication session. The response contains a redirectUrl — send the user's browser there to begin authentication.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
audit.externalReference |
string | Yes | Your reference for this authentication (stored in audit log) |
audit.context |
string | No | Optional freeform context string |
returnUrl |
string | Yes | Absolute URL the user is redirected to after authentication. Receives status, sessionId, and optionally state and reason as query parameters |
errorRedirectUrl |
string | No | Absolute URL used on failure or cancellation. Defaults to returnUrl if omitted |
clientState |
string | No | Opaque value echoed back as a query parameter on redirect — useful for correlating with your own session |
needNationalIdentifier |
boolean | No | Request the user's CPR number (Denmark) or national identifier. See CPR step-up below |
requestedLoa |
string | No | Minimum level of assurance required: Low, Substantial (default), High |
authLevel |
string | No | Normal allows SSO (default). Fresh forces the user to actively re-authenticate even if they have an active session |
Response:
| Field | Type | Description |
|---|---|---|
sessionId |
string | Use this when calling /result after authentication |
brokerId |
string | The broker handling this session |
redirectUrl |
string | Redirect the user's browser to this URL |
expiresAtUtc |
string (ISO 8601) | Session expiry — the user must complete authentication before this time |
Retrieve result — `POST /api/auth/
Call this after the user has been redirected back to your returnUrl with status=success.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
audit.externalReference |
string | Yes | Your reference (stored in audit log) |
audit.context |
string | No | Optional context string |
sessionId |
string | Yes | The session ID from the /start response |
Response — normalized identity:
| Field | Type | Description |
|---|---|---|
providerId |
string | Broker used (e.g. mitid, bankid_no) |
identityScheme |
string | Identity scheme (e.g. mitid, bankid, eidas) |
levelOfAssurance |
string | Achieved assurance level: low, substantial, or high |
subject |
string | Permanent, stable identifier for this user from the provider. Use as your primary user key — see note below |
name |
string | Full display name |
givenName |
string | First name (if provided by broker) |
familyName |
string | Last name (if provided by broker) |
dateOfBirth |
string | ISO 8601 date (YYYY-MM-DD), if available |
country |
string | ISO 3166-1 alpha-2 country code (e.g. DK) |
nationalIdentifier |
string | CPR or national ID, if requested and available |
age |
integer | Calculated from dateOfBirth, if available |
hasNameAndAddressProtection |
boolean | true if the user has name/address protection (Danish navne- og adressebeskyttelse) |
issuedAt |
string (ISO 8601) | When the identity token was issued |
expiresAt |
string (ISO 8601) | When the identity token expires |
rawClaims |
object | Key-value map of the original provider claims, for debugging |
The subject field
The subject is a permanent, stable identifier assigned to the user by the identity provider (e.g. the MitID UUID). It:
- Never changes for a given user, even if their name or address changes
- Is unique per user within a given provider
- Should be stored and used as the primary key to recognize returning users
Recommendation: Store subject on first authentication and use it to look up the user on subsequent logins — do not rely on name or date of birth for identity matching.
Return URL parameters
After authentication, the user is redirected to your returnUrl (or errorRedirectUrl) with the following query parameters:
| Parameter | Values | Description |
|---|---|---|
status |
success, failed, cancelled |
Outcome of the authentication |
sessionId |
string | Session ID to use when calling /result (only on success) |
state |
string | Echo of your clientState from the start request |
reason |
string | Human-readable error description (on failed or cancelled) |
Only call /result when status=success. On failed or cancelled, the session cannot be used to retrieve identity data.
National identifier (CPR) step-up
When needNationalIdentifier: true, the system automatically handles CPR collection with minimal friction:
First-time users: After MitID authentication, the user is prompted once to enter their CPR number — no re-login required.
Returning users: CPR is retrieved from the stored session automatically. The user never sees an additional prompt.
This step-up happens within the same authentication session, so users only ever need to authenticate once regardless of whether CPR is required.
Error reference
| Status | Meaning |
|---|---|
400 |
Invalid request (e.g. returnUrl is not absolute, missing required fields) |
403 |
Your client is not configured for the requested broker |
404 |
Session not found or expired |