Skip to main content
Both integrations end at the same payload.

Overview

  • Who is the user? → returned under user.
  • Which connection verified them? → provenance._metadata.provider_id, connection_id, credential_id, and connection_instance_id within the same metadata block.
  • How was this identity verified? → described by provenance.
  • Did the user’s claimed values match the source? → returned under match for match connections.
This data model is served by OIDC /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

Under provenance._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 v2. 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-level verification_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 under user 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 in userInput.
  • Stable on one connection only. Values aren’t namespaced: two connections can return the same value for one person, or different values. Store source_id together with the connection: hopae_verification.connection_id in the ID token, or provenance._metadata.connection_id in userinfo (with provenance=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_id that can’t be derived is listed in missing_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 match for the outcome.
  • It can widen the provider request. Selecting source_id makes Hopae request the claims it is derived from. Get Connections lists them in sourceIdBackedBy. They aren’t returned under user unless 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 claims exactly 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.
  • Metadata
    • Catalog identity, verification identifiers, and timestamps for audit and support (verification_id, verified_at, status, and error when the session ended with an error).
Read 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).

Next Steps

OIDC Provider

How OIDC fits into User Verification

Verification Flow

Understand the end-to-end lifecycle