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
Filter enabled connections by a minimum supported Level of Assurance: urn:hopae:loa:{level} (1 to 5). Hopae records the achieved level in acr / hopae_loa. If it is lower than requested, the verification is still finished, and userinfo requested with provenance=true carries provenance._metadata.error.code = "loa_insufficient" so you can decide. A filter leaving no eligible connection finishes with invalid_request. 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 simply means no pre-selection. 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.
​
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.
  • On failure or cancellation, redirects with error=access_denied and an error_description, plus state if provided. A missing or unregistered redirect_uri cannot be redirected and shows a hosted error page instead.

​
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

Minimum Level of Assurance, urn:hopae:loa:{1-5}.

​
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, or with error=access_denied.