Skip to main content
Hopae Connect is an OpenID Provider. You redirect the user to Hopae, Hopae runs the verification, and your backend exchanges the returned code for the verified data. Any certified OIDC client library works. Before you start
  • 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

Configure your library with the issuer https://connect.hopae.com and override the authorization endpoint with /v2/auth. Discovery lists /auth, which is the v1 API. The endpoint where the verification starts decides the response format, so the token and userinfo endpoints from discovery also work.

1. Redirect to /auth

All parameters, including the ui_* display options and private_mode: Authorization reference.

Pre-select a connection

Pass ui_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
Check 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.
You receive an 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

Read identity data from 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 to https://connect.hopae.com and override the authorization endpoint with https://connect.hopae.com/v2/auth. These libraries also validate the ID token for you.

Troubleshooting

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.
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.
The code expired (5 minutes) or was already used, or redirect_uri differs from the authorization request.
Send the App ID and App Secret of the same app as HTTP Basic credentials.
Add hopae to scope.
Activate a connection and enable it in the workflow you run. Production apps need their own activations.
Native app? Keep the token exchange on your backend. A few connections don’t run in a WebView: see Mobile App Integration.