> ## 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 three fields:

* `hopae_loa` — integer 1–5 level for programmatic checks
* `hopae_loa_label` — human-readable label (e.g., `substantial`)

## 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–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+     |

## Specify LoA in requests

Request a minimum LoA when initiating verification:

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

    ```http theme={null}
    GET https://sandbox.connect.hopae.com/auth
      ?client_id=YOUR_CLIENT_ID
      &redirect_uri=https://example.com/callback
      &response_type=code
      &scope=openid idv
      &acr_values=urn:hopae:loa:3
    ```

    See [acr\_values format](/guides/oidc-integration#acr_values-format) for additional options including provider filtering.
  </Tab>

  <Tab title="REST API">
    Include `requestedLoa` in the request body:

    ```json Request Body theme={null}
    {
      "providerId": "smartid",
      "requestedLoa": 3,
      "redirectUri": "https://example.com/callback"
    }
    ```
  </Tab>
</Tabs>

When not specified, the provider's minimum supported LoA is used.

## Error handling

**Provider does not support the requested LoA**

Returns an error before authentication begins:

* OIDC: Error callback redirect
* REST API: HTTP 422

```json theme={null}
{
  "code": "VALIDATION_UNPROCESSABLE",
  "detail": "Cannot process 'requestedLoa': Requested LoA exceeds provider's maximum supported level",
  "context": {
    "parameter": "requestedLoa",
    "value": 5,
    "providerId": "frejaid"
  }
}
```

**If the final LoA is lower than requested**

This can occur when:

* The user chooses a weaker authentication method than expected
* The provider downgrades the session due to fallback mechanisms

The verification status becomes `failed`, but you can still retrieve user data via the `/userinfo` endpoint.
This allows you to decide how to handle the situation

```json theme={null}
{
  "verificationId": "dd0f6ffef6124e95b3001dbb44a6317e",
  "status": "failed",
  "providerId": "bankidse",
  "flowType": "redirect",
  "error": {
    "type": "loa_validation",
    "code": "loa_insufficient",
    "message": "Achieved LoA '3' is below requested '5'"
  },
  "hopae_loa": 3,
  "hopae_loa_label": "substantial"
}
```

## Response example

LoA fields are included in both ID Token and UserInfo responses:

```json theme={null}
{
  "sub": "wPqH84Q4pDiE4qWWIfGeMQcoctqYfNVf",
  "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](/guides/oidc-integration) — `acr_values` parameter usage
* [REST API: Create Verification](/api-reference/verifications/create-verification) — `requestedLoa` field