Overview
- Who is the user? → returned under
user. - Which connection verified them? →
provenance._metadata.provider_id,connection_id,credential_id, andconnection_instance_idwithin the same metadata block. - How was this identity verified? → described by
provenance. - Did the user’s claimed values match the source? → returned under
matchfor match connections.
/userinfo (subject to granted scopes and the OIDC claim whitelist) and by the REST Get Verification UserInfo endpoint. On both, provenance and missing_claims are returned only when the request asks for them with provenance=true and missing_claims=true.
Connection identity
Underprovenance._metadata, every userinfo result requested with provenance=true names the connection that ran, using the same ids you see in the Console and in Get Connections:
There is no
amr claim in the v2 ID token or userinfo. The ID token carries provider_id and connection_id inside one hopae_verification claim. credential_id and connection_instance_id are only in the userinfo response’s provenance._metadata. All four identifiers are nested there in userinfo, never top-level.
Verification models
The top-levelverification_model field tells you which payload shape to read:
verification_model is always present and is decided by the connection you verify against.
For match flows, user echoes back the verified subset of the values you submitted. Per-field providers: only fields with matched: true. Aggregate providers: every submitted field when the aggregate outcome is true, otherwise empty. A match connection may additionally expose disclosed (provider-asserted) claims. Those appear under user only when they are requested (in the workflow, or in requestedClaims on REST), and a requested-but-unavailable claim is listed in missing_claims.
For match connections, the values to compare are supplied at session creation in userInput. The keys are OIDC-normalized names (see Normalized User Data) and appear back in match.submitted_fields and as match.details keys. See User Input.
Which claims you receive
The claims underuser are the ones the workflow requested: the claims on its Claims tab, plus any claims set for the connection that ran. A non-empty requestedClaims in Create Verification replaces this set.
Source ID
sub is not a stable user identifier: it is the verification id and changes on every verification. To recognise a returning person, use source_id.
source_id is opt-in in v2. Tick Source ID on the workflow’s Claims tab, or include source_id in requestedClaims on REST, to receive it. A Quickstart sandbox app’s workflow starts with it ticked.
- What it is. The source’s identifier for the person, copied as-is. Usually a national or personal number, or the identity provider’s own
sub. For some match connections, it is the value you sent inuserInput. - Stable on one connection only. Values aren’t namespaced: two connections can return the same value for one person, or different values. Store
source_idtogether with the connection:hopae_verification.connection_idin the ID token, orprovenance._metadata.connection_idin userinfo (withprovenance=true). - It can change. The value changes when the source claim behind it changes (for example a reissued document), and when the connection falls back to its second source because the first is missing.
- It may be missing. Not every connection provides one, and a connection that does may not for every person. A requested
source_idthat can’t be derived is listed inmissing_claims. - Treat it as personal data. It is often a national identification number and is not hashed.
- On match connections it is not proof of a match. When it is the value you sent, it is returned whatever the match outcome. Read
matchfor the outcome. - It can widen the provider request. Selecting
source_idmakes Hopae request the claims it is derived from. Get Connections lists them insourceIdBackedBy. They aren’t returned underuserunless you request them too.
What “Provenance” means
Provenance is the audit trail of the verification: what the source actually returned, and when.- Presentation
- Credentials[]: one entry per credential the source presented, carrying the source’s own
claimsexactly as received (for match connections too) and, when the provider issues it,evidence. - Evidence (when present)
- The original signed proof from the source (or a Hopae-signed equivalent when the provider issues none), so you can independently verify the result wasn’t altered in transit. Shape and keys vary by provider. See Evidence & Data Integrity.
- Credentials[]: one entry per credential the source presented, carrying the source’s own
- Metadata
- Catalog identity, verification identifiers, and timestamps for audit and support (
verification_id,verified_at,status, anderrorwhen the session ended with an error).
- Catalog identity, verification identifiers, and timestamps for audit and support (
provenance._metadata for the catalog provider, credential, connection, and activated instance IDs. These are snapshotted when the session starts. Resolve issuer details through the catalog and source evidence.
UserInfo payload structure
Here is a conceptual map of the payload. For detailed field specifications, refer to the Data Types pages.Match payload example
A complete userinfo response from a match connection (id-nik-match, Indonesia NIK):
For match connections,
provenance.presentation.credentials[].claims carries the source’s own response. This is the audit trail for what the source agreed with. It is not a duplicate of match.details. Note the intentional naming asymmetry: userInput, match.submitted_fields, and match.details use OIDC-normalized keys (e.g. name, birthdate), while provenance claims keep the source’s native keys (e.g. fullName, dateOfBirth) so the audit trail stays aligned with the source.details may include keys that are not in submitted_fields when the upstream provider emits additional verifier results (e.g., a liveness signal alongside the demographic match outcome).Related
Next Steps
OIDC Provider
How OIDC fits into User Verification
Verification Flow
Understand the end-to-end lifecycle

