> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Level of Assurance (LoA)

> How to request and validate authentication assurance levels.

## Overview

Level of Assurance (LoA) indicates the confidence level of an identity verification. Based on the OIDC `acr` (Authentication Context Class Reference) claim, Hopae returns:

* `hopae_loa`: integer level from 1 to 5 for programmatic checks
* `hopae_loa_label`: human-readable label (e.g., `substantial`)
* `acr`: the `urn:hopae:loa:{level}` URN, present when the provider asserted the level explicitly

## LoA levels

| acr | hopae\_loa | hopae\_loa\_label | Description | eIDAS | NIST |
| - | - | - | - | - | - |
| `urn:hopae:loa:1` | 1 | `none` | No verified ID link | - | IAL1/AAL1 |
| `urn:hopae:loa:2` | 2 | `low` | Limited KYC | Low | IAL1 to 2 |
| `urn:hopae:loa:3` | 3 | `substantial` | Trusted eID, strong single factor | Substantial | IAL2/AAL2 |
| `urn:hopae:loa:4` | 4 | `high` | Multi-factor + crypto binding | High | IAL3/AAL3 |
| `urn:hopae:loa:5` | 5 | `qualified` | Qualified signature | High+/QES | IAL3+ |

Every connection advertises the levels its credential can reach as `credential.loa[]` in [Get Connections](/v2/api-reference/verifications/get-connections) and in the Console's Connections table.

## Require a minimum LoA

<Tabs>
  <Tab title="Workflow (recommended)">
    Add a `check-min-loa` node after the verification step so the requirement travels with the workflow and applies to both OIDC and REST:

    ```json theme={null}
    { "id": "nd_gate", "type": "check-min-loa", "next": "nd_resp", "config": { "minLoa": 3 } }
    ```

    The userinfo response then carries `metLoa` so you can branch on it. See [Workflow Nodes](/v2/guides/reference/workflow-nodes).
  </Tab>

  <Tab title="OIDC">
    Add the `acr_values` query parameter:

    ```http theme={null}
    GET https://connect.hopae.com/v2/auth
      ?client_id=YOUR_APP_ID
      &redirect_uri=https://example.com/callback
      &response_type=code
      &scope=openid hopae
      &acr_values=urn:hopae:loa:3
    ```
  </Tab>

  <Tab title="REST API">
    The v2 Verification REST API has no per-request LoA parameter. Choose connections whose `credential.loa[]` meets your requirement, gate with a workflow `check-min-loa` node, or check `hopae_loa` on the userinfo response yourself.
  </Tab>
</Tabs>

When no level is requested, the connection's minimum supported LoA applies.

## When the achieved LoA is lower than requested

This can occur when the user chooses a weaker authentication method than expected, or the provider downgrades the session through a fallback mechanism.

The verification is still **finished** and the result is returned, so you can decide what to do. REST userinfo carries the achieved level in `hopae_loa` and a top-level `error`. In OIDC, check the achieved level and `provenance._metadata.error`. The top-level `error` is not included in the OIDC claims whitelist:

```json theme={null}
{
  "user": {
    "given_name": "Lars",
    "family_name": "Nielsen"
  },
  "missing_claims": [],
  "hopae_loa": 2,
  "hopae_loa_label": "low",
  "verification_model": "disclosure",
  "error": {
    "code": "loa_insufficient",
    "message": "Provider LoA 2 is below the requested minimum 3"
  },
  "provenance": {
    "...": "...",
    "_metadata": {
      "provider_id": "mitid",
      "connection_id": "mitid",
      "credential_id": "mitid",
      "connection_instance_id": "conn_01J8XM0R7C2VHK4Y"
    }
  },
  "sub": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8"
}
```

Over REST, [Get Verification Status](/v2/api-reference/verifications/get-verification) reports `status: "failed"` with `error.code: "loa_insufficient"`. The userinfo endpoint still serves this one failed state.

## Response example

LoA fields are included in both the ID token and the userinfo response:

```json theme={null}
{
  "sub": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
  "acr": "urn:hopae:loa:4",
  "hopae_loa": 4,
  "hopae_loa_label": "high",
  "user": {
    "name": "Anders Eriksson"
  }
}
```

<Warning>
  Always validate `hopae_loa` server-side before granting access to sensitive operations.
</Warning>

```js theme={null}
if (claims.hopae_loa >= 3) {
  // allow sensitive action
}
```

## See also

* [OIDC Integration Guide](/v2/guides/oidc-integration): `acr_values` parameter usage
* [Workflow Nodes](/v2/guides/reference/workflow-nodes): the `check-min-loa` node
* [Get Connections](/v2/api-reference/verifications/get-connections): `credential.loa[]` per connection


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.