# 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](https://wiki.nuts.nl/link/201), so the other party knows which user requests the data.

<div class="callout info" markdown="1">

**Use case design (spec v1)**

The use case specifies whether an access token request needs a user identity, and which means it accepts.
</div>

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:

```yaml
auth:
  publicurl: https://<public domain>
```

## 1. Draw up a contract

```
PUT <internal Nuts interface>/internal/auth/v1/contract/drawup
```
```json
{
  "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](https://wiki.nuts.nl/link/198): 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
```
```json
{
  "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:

```json
{
  "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
```
```json
{
  "means": "irma",
  "payload": "<message>"
}
```

Show the QR code to the user with [irma-frontend-packages](https://github.com/privacybydesign/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:

```javascript
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:

```yaml
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>
```
```json
{
  "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
```
```json
{
  "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)](https://nuts-node.readthedocs.io/en/v5.4/pages/integrating/api.html)