Authenticate users
In spec v1, the user signs a login contract: a statement that they act on behalf of a care organization, valid for a limited time.
The signed contract is a Verifiable Presentation. You send it as identity in an access token request, see Request an access token, so the other party knows which user requests the data.
The use case specifies whether an access token request needs a user identity, and which means it accepts.
The Nuts node supports two means to sign a contract:
| Means | User needs | Identifies the user by | username in the access token |
assurance_level |
|---|---|---|---|---|
Employee identity (employeeid) |
A browser | The care organization's statement about its employee (identifier, name, role) | The identifier you pass | low |
IRMA (irma) |
The IRMA (Yivi) app, with their BRP and email credentials | Attributes from the app (name, email) | The email address | From the DigiD level: low, substantial or high |
Prerequisites
The user's browser or app talks to the Nuts node directly. So:
- the
/publicAPIs of the node must be reachable over HTTPS from the internet, without extra access restrictions; auth.publicurlmust be set to the URL they're reachable on:
auth:
publicurl: https://<public domain>
1. Draw up a contract
PUT <internal Nuts interface>/internal/auth/v1/contract/drawup
{
"type": "BehandelaarLogin",
"language": "NL",
"version": "v3",
"legalEntity": "<care organization DID>",
"validFrom": "2026-01-02T15:04:05+01:00",
"validDuration": "2h"
}
type/language:BehandelaarLoginwithNL, orPractitionerLoginwithEN.version:v3.legalEntity: the care organization the user acts for. Your node must manage its DID, and it needs a NutsOrganizationCredential, see Register, find and authorize care organizations: its name and city are in the contract text.validFrom: RFC3339 time, optional (default: now).validDuration: e.g.2hor60m(units:s,m,h), optional (default: 60 minutes).
If the care organization has NutsOrganizationCredentials with different names or cities, the request fails. Then pass the one to use as organizationCredential.
The response contains the contract text in message, e.g.:
EN:PractitionerLogin:v3 I hereby declare to act on behalf of CareBears located in CareTown. This declaration is valid from Monday, 2 January 2026 15:04:05 until Monday, 2 January 2026 17:04:05.
2a. Sign with employee identity
Start a signing session with the contract text as payload:
POST <internal Nuts interface>/internal/auth/v1/signature/session
{
"means": "employeeid",
"payload": "<message>",
"params": {
"employer": "<care organization DID>",
"employee": {
"identifier": "<unique user ID, e.g. email address or employee number>",
"initials": "<initials>",
"familyName": "<family name>",
"roleName": "<role>"
}
}
}
All fields are required, except roleName: the user's role in the care organization, readable by people.
The response:
{
"sessionID": "<session ID>",
"means": "employeeid",
"sessionPtr": {
"sessionID": "<session ID>",
"url": "https://<public domain>/public/auth/v1/means/employeeid/<session ID>"
}
}
Show the page at sessionPtr.url to the user (iframe, pop-up or browser window), where they confirm the contract. The user has 10 minutes to do so.
2b. Sign with IRMA
Start a signing session with the contract text as payload:
POST <internal Nuts interface>/internal/auth/v1/signature/session
{
"means": "irma",
"payload": "<message>"
}
Show the QR code to the user with irma-frontend-packages; the user scans it with the app. The frontend can't call the node's internal API, so your backend provides two endpoints for it:
| Your backend endpoint | Does |
|---|---|
<url>/session |
Draws up the contract, starts the session as above, returns the node's response as-is |
<url>/session/<sessionID>/result |
Returns the session result, see step 3 |
In the frontend options, set session.url to <url> and map the node's response:
mapping: {
sessionPtr: r => r.sessionPtr.clientPtr,
sessionToken: r => r.sessionID
}
The app talks to the node at <auth.publicurl>/public/auth/irmaclient. If your frontend runs on another domain, allow it with CORS:
http:
default:
cors:
origin: "<frontend domain>"
Use alt.public instead of default if the public APIs run on a separate interface.
3. Get the signed contract
Poll the session from your backend:
GET <internal Nuts interface>/internal/auth/v1/signature/session/<sessionID>
{
"status": "completed",
"verifiablePresentation": { ... }
}
status:created,in-progress,completed,cancelled,erroredorexpired(IRMA uses its own values). Use it to show progress to the user.verifiablePresentation: the signed contract. It's only there when signing succeeded. Store it in the user's session.
With employee identity, you get the signed contract once: only the first response with completed contains it. After that, the node removes the session: later calls don't return the contract and end in 404. A cancelled, errored or expired session is also removed once you've read its status.
4. Check the signed contract before using it
The contract expires (validDuration). Check it before you send it:
PUT <internal Nuts interface>/internal/auth/v1/signature/verify
{
"VerifiablePresentation": <signed contract>
}
Add checkTime (RFC3339) to check at another moment than now. validity is false when the contract is invalid or expired. Then let the user sign a new one.
API reference: Auth (v1)