Skip to main content

Lifecycle

A verification is created against one connection and ends in one of two final statuses, completed or failed. It expires at expiresAt, 30 minutes after creation, if it has not finished.
processing appears in the schema but is never returned. If you see it, treat it like authenticating.
A verification in a final status always has result.code. See Result Codes for every code and what to do next. A verification belongs to the app that created it. Read and cancel it with the same app’s credentials. Any other app gets 404.

Expiry

Expiry is not a status, and the API does not return it. It is decided by time alone: a verification that has not finished by its expiresAt has expired. Start a new one. A verification gets a final status only when its result is known. If the result is not known by expiresAt, the verification expires without a final status. Every verification, finished or not, is kept only until expiresAt. After that, every call for it returns 404. So read expiresAt from the create response, stop waiting when it passes, and read userinfo as soon as result.code is RECEIVED. The Console’s Security & Compliance → Audit Log keeps the record and shows it as expired. No webhook is sent for expiry.

Flow types

The connection decides the flow type. With OIDC, Hopae handles every flow for you. With the REST API, your app does the user-facing part.

Flow types in detail

Sequence diagrams, full responses, and same-device handling for each flow type.

The hosted flow

With OIDC, the user selects country → credential → provider on a Hopae-hosted page. Only connections enabled in the workflow are offered. The provider step appears only when a credential is available through more than one provider. To skip the picker, pass ui_connection_id. See OIDC Integration.