Skip to main content
GET
Start a verification by redirecting the user’s browser to the shared /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

string
required
Your App ID.
string
required
Exact match to a redirect URI registered for this app (Console → Developers → API Settings → Redirect URL Allowlist). Saving the app’s allowlist takes effect immediately. See Apps & Environments.
string
default:"code"
required
Must be code.
string
default:"openid hopae"
required
Space-delimited scopes. Include openid and hopae (or the equivalent idv). Without hopae/idv, the userinfo response contains no user, provenance, match, or missing_claims.
string
Opaque value echoed back on the redirect. Use it for CSRF protection.
string
Bound into the ID token. Recommended for browser-based clients.
string
login forces a fresh verification. Hopae never reuses a previous verification, so this is mainly for client libraries that expect it.
string
The workflow to run (Console → Workflow → copy the workflow ID). Defaults to the app’s default workflow. The workflow decides which connections are offered and which claims are requested. An unknown explicit workflow produces invalid_request. An app with no workflow shows a hosted error page (WORKFLOW_NOT_CONFIGURED) and does not redirect back.
string
The Level of Assurance to ask the provider for: 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, or ui_provider_id names only connections that don’t support the level. A hint that names no enabled connection is ignored, as it is without acr_values.
The provider asks the user to sign in at that level, so 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.
string
Pre-select a connection so the user skips country and credential selection. Use the catalog connection id (for example 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.
string
Catalog provider id. Pre-selects its single enabled connection. If none or several match, the hosted selection screen remains visible. Unlike REST creation, ambiguity does not return a 400. With an acr_values level, only the connections that support it count, and at least one must: see acr_values.
string
Use with 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.
string
Pre-select the country step (ISO 3166-1 alpha-2).
boolean
true skips the hosted intro screen and lands on the selection step.
boolean
true hides the back button in the hosted UI.
boolean
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.
The v1 parameters 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 Found to your redirect_uri with code and state query params. The code is single-use and expires after 5 minutes. A verification that ends with result.code RECEIVED is a success.
  • On failure or cancellation, redirects with error=access_denied and an error_description, plus state if provided.
    • When the verification ended with a code other than RECEIVED, including one whose start failed at the provider, the redirect also carries status and result_code. error_description is the result’s message.
    • When the request to start was refused and no verification exists, the redirect carries no status or result_code.
  • When Hopae can’t process the request, such as an unknown workflow_id or an acr_values level that the workflow’s connections don’t support, redirects with error=invalid_request and an error_description that names the cause. These errors carry no status or result_code. A missing or unregistered redirect_uri cannot be redirected and shows a hosted error page instead.
See Result Codes for every result_code.

Examples

Authorizations

Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Query Parameters

client_id
string
required

Your App ID.

redirect_uri
string
required

A redirect URI registered for the app.

response_type
enum<string>
default:code
required

Must be code.

Available options:
code
scope
string
default:openid hopae
required

Include openid and hopae.

state
string

Echoed back on the redirect. Use it for CSRF protection.

nonce
string

Bound into the ID token.

workflow_id
string

Workflow to run. Defaults to the app's default workflow.

acr_values
string

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.

ui_connection_id
string

Pre-select a connection by catalog id, for example smart-id.

ui_country
string

Pre-select the country (ISO 3166-1 alpha-2).

ui_skip_intro
boolean

Skip the intro screen.

ui_hide_back_button
boolean

Hide the back button.

Response

302

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).