Skip to main content

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.

**

Use case design (spec v1)**

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 /public APIs of the node must be reachable over HTTPS from the internet, without extra access restrictions;
  • auth.publicurl must 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: BehandelaarLogin with NL, or PractitionerLogin with EN.
  • 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. 2h or 60m (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, errored or expired (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)