Skip to main content

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.

​
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

acrhopae_loahopae_loa_labelDescriptioneIDASNIST
urn:hopae:loa:11noneNo verified ID link-IAL1/AAL1
urn:hopae:loa:22lowLimited KYCLowIAL1–2
urn:hopae:loa:33substantialTrusted eID; strong single factorSubstantialIAL2/AAL2
urn:hopae:loa:44highMulti-factor + crypto bindingHighIAL3/AAL3
urn:hopae:loa:55qualifiedQualified signatureHigh+/QESIAL3+

​
Specify LoA in requests

Request a minimum LoA when initiating verification:
Add acr_values query parameter:
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 for additional options including provider filtering.
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
{
  "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 
{
  "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: 
{
  "sub": "wPqH84Q4pDiE4qWWIfGeMQcoctqYfNVf",
  "acr": "urn:hopae:loa:4",
  "hopae_loa": 4,
  "hopae_loa_label": "high",
  "user": {
    "name": "Anders Eriksson"
  }
}
Always validate hopae_loa server-side before granting access to sensitive operations.
if (claims.hopae_loa >= 3) {
  // allow sensitive action
}

​
See also