- An app’s App ID (
client_id) and App Secret (client_secret) from Developers → API Settings. - Your redirect URI in that app’s Redirect URL Allowlist, on the same Developers → API Settings page. Matching is exact.
- At least one connection that is activated and enabled in the app’s workflow.
Endpoints
1. Redirect to /auth
All parameters, including the
ui_* display options and private_mode: Authorization reference.
Pre-select a connection
Passui_connection_id (for example smart-id) to skip the country and eID picker. The connection must be enabled in the workflow. Otherwise the user selects a connection as usual. If you also send an acr_values level, the connection must support it, or the authorization ends with invalid_request. ui_country pre-selects only the country.
2. Handle the callback
Success
Failure
state, and iss if your library supports it (https://connect.hopae.com). A verification that ends as RECEIVED arrives with an authorization code. Any other ending arrives as error=access_denied with status and result_code. When no verification exists, error=access_denied arrives without them. See Result Codes. The authorization expires 30 minutes after /v2/auth. After that the user sees Hopae’s error page and your callback is not called. An unknown workflow_id, or an acr_values level that the workflow’s connections don’t support, arrives as error=invalid_request, without status or result_code. See Behavior. An app without a workflow shows an error page instead of redirecting.
3. Exchange the code
On your backend, with your App ID and App Secret as HTTP Basic credentials (client_secret_basic). Form fields (client_secret_post) also work. Codes are single-use and expire after 5 minutes.
access_token (10 minutes) and an id_token (30 minutes). No refresh token is issued. Every verification is a new authorization.
The ID token carries no personal data. Validate its signature (JWKS), iss (https://connect.hopae.com), aud (your App ID), and nonce. It names the level of assurance (hopae_loa, plus acr when the connection determined the level) and the connection that ran (hopae_verification.connection_id). Details: Token reference.
4. Read the result
user. Add ?provenance=true&missing_claims=true for the audit trail and the claims the source could not provide. The payload is the same as the REST API’s. See Return Data.
To recognise a returning person, use user.source_id together with the connection, not sub. source_id is opt-in and stable only on the same connection. See Source ID.
Library examples
Any certified OIDC library works: set the issuer tohttps://connect.hopae.com and override the authorization endpoint with https://connect.hopae.com/v2/auth. These libraries also validate the ID token for you.
- Node.js
- Java (Spring)
Troubleshooting
Hosted error page instead of a redirect
Hosted error page instead of a redirect
The
redirect_uri is not on the allowlist of the app named by client_id. Scheme, host, port, path, and trailing slash must match exactly.invalid_request on the callback
invalid_request on the callback
error_description names the cause. For an unknown workflow_id, copy the ID again from the Console. For an acr_values level, enable a connection that supports the level in the workflow, or remove acr_values. See Request a target LoA.invalid_grant at /token
invalid_grant at /token
The code expired (5 minutes) or was already used, or
redirect_uri differs from the authorization request.invalid_client at /token
invalid_client at /token
Send the App ID and App Secret of the same app as HTTP Basic credentials.
userinfo has no user data
userinfo has no user data
Add
hopae to scope.No eIDs offered on the hosted page
No eIDs offered on the hosted page
Activate a connection and enable it in the workflow you run. Production apps need their own activations.

