GET https://connect.hopae.com/v2/auth?client_id=xhdh8a13&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&response_type=code&scope=openid%20hopae&state=rf9Xy1&nonce=n-0S6_WzA2Mj&workflow_id=wf_01J8XJ4Q2R7TPX9K
HTTP/1.1 302 Found
Location: https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=rf9Xy1&iss=https%3A%2F%2Fconnect.hopae.com
Start Authorization
Initiates the OIDC Authorization Code flow. Front-channel redirect. No Authorization header.
GET https://connect.hopae.com/v2/auth?client_id=xhdh8a13&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&response_type=code&scope=openid%20hopae&state=rf9Xy1&nonce=n-0S6_WzA2Mj&workflow_id=wf_01J8XJ4Q2R7TPX9K
HTTP/1.1 302 Found
Location: https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=rf9Xy1&iss=https%3A%2F%2Fconnect.hopae.com
/v2/auth endpoint with your app’s client_id. Hopae hosts the verification UI, runs the eID flow, and returns the user to your redirect_uri with an authorization code.
Query Parameters
openid and hopae (or the equivalent idv). Without hopae/idv, the userinfo response contains no user, provenance, match, or missing_claims.login forces a fresh verification. Hopae never reuses a previous verification, so this is mainly for client libraries that expect it.invalid_request. An app with no workflow shows a hosted error page (WORKFLOW_NOT_CONFIGURED) and does not redirect back.urn:hopae:loa:{level} (1 to 4). It follows the same rule as requestedLoa in Create Verification: only a connection with acceptsRequestedLoa: true in Get Connections whose highest credential.loa level is at least {level} supports it. The user is offered only the connections that support it. If only one does, it’s pre-selected.The authorization ends with invalid_request in either of these cases:- No connection in the workflow supports the level.
ui_connection_instance_id,ui_connection_id, orui_provider_idnames only connections that don’t support the level. A hint that names no enabled connection is ignored, as it is withoutacr_values.
hopae_loa is at least {level}. To require a minimum, check hopae_loa yourself or add a check-min-loa node to the workflow. The v1 urn:hopae:id:{providerId} token is ignored on /v2: it neither narrows nor rejects. Use the ui_* pre-selection hints instead. See Level of Assurance.smart-id) of a connection enabled in the workflow. An id that is not enabled means no pre-selection. With an acr_values level, the connection must support it: see acr_values. Replaces the v1 ui_provider parameter. ui_connection_instance_id with the instance id (conn_…) is also accepted.acr_values level, only the connections that support it count, and at least one must: see acr_values.ui_provider_id to narrow to one credential. Hint precedence is instance → connection → provider. An unmatched connection hint does not fall through to the provider hint.true runs the verification but blocks token and userinfo issuance (403 AUTH_DATA_PROTECTED). Use it when you only need the result recorded on Hopae’s side.ui_provider, ui_auth_flow, ui_hide_header, and ui_need_consent have no effect on v2. The hosted flow always runs country → credential → provider.Behavior
- On success, responds with
302 Foundto yourredirect_uriwithcodeandstatequery params. The code is single-use and expires after 5 minutes. A verification that ends withresult.codeRECEIVEDis a success. - On failure or cancellation, redirects with
error=access_deniedand anerror_description, plusstateif provided.- When the verification ended with a code other than
RECEIVED, including one whose start failed at the provider, the redirect also carriesstatusandresult_code.error_descriptionis the result’s message. - When the request to start was refused and no verification exists, the redirect carries no
statusorresult_code.
- When the verification ended with a code other than
- When Hopae can’t process the request, such as an unknown
workflow_idor anacr_valueslevel that the workflow’s connections don’t support, redirects witherror=invalid_requestand anerror_descriptionthat names the cause. These errors carry nostatusorresult_code. A missing or unregisteredredirect_uricannot be redirected and shows a hosted error page instead.
result_code.
Examples
GET https://connect.hopae.com/v2/auth?client_id=xhdh8a13&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&response_type=code&scope=openid%20hopae&state=rf9Xy1&nonce=n-0S6_WzA2Mj&workflow_id=wf_01J8XJ4Q2R7TPX9K
HTTP/1.1 302 Found
Location: https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=rf9Xy1&iss=https%3A%2F%2Fconnect.hopae.com
HTTP/1.1 302 Found
Location: https://app.example.com/callback?error=access_denied&error_description=The%20user%20cancelled%20the%20verification.&status=failed&result_code=USER_CANCELLED&state=rf9Xy1
Authorizations
Query Parameters
The Level of Assurance to ask the provider for, urn:hopae:loa:{1-4}. Only a connection with acceptsRequestedLoa: true in GET /connections whose highest credential.loa level is at least the requested level supports it, and only those connections are offered. If no connection in the workflow supports it, or ui_connection_instance_id, ui_connection_id, or ui_provider_id names only connections that don't, the authorization ends with invalid_request. The provider asks the user to sign in at that level, so hopae_loa is at least the requested level. To require a minimum, check hopae_loa yourself or add a check-min-loa workflow node.
Response
Redirect to redirect_uri with code and state when the result code is RECEIVED, with error=access_denied plus status and result_code for any other result, with error=access_denied alone when no verification exists, or with error=invalid_request (a request Hopae can't process, such as an unknown workflow_id or an acr_values level the workflow's connections don't support).

