Handling the callback

Three checks before you trust anything

Also verify the ID token's iss against the discovery issuer, its aud against your client id, its signature against the JWKS at jwks_uri, and its expiry. claims_supported on the discovery document lists sub, aud, iss, exp, iat, nonce, auth_time, acr, amr, identity_verified, consent_id, first_sign_in and connected_at.

{
  "iss": "https://api.unifyid.example",
  "sub": "sub_7Xk…",
  "aud": "vid_live_example",
  "nonce": "…",
  "auth_time": 1788868800,
  "amr": ["fido2"],
  "acr": "urn:unifyid:assurance:standard",
  "identity_verified": true,
  "first_sign_in": false,
  "connected_at": "2026-08-01T09:00:00.000Z",
  "iat": 1788868810,
  "exp": 1788869710
}

A private sign-in application's ID token has no auth_time, amr or acr. See What the application receives.

The denial path

Cancel on the consent screen is RFC 6749 access_denied at your redirect URI. So is a sign-in attempt by a person whose identity verification failed, is under review, or whose account is restricted — which is exactly why three of the four test-identity scenarios refuse.

Your callback must therefore handle an error parameter as a first-class outcome, not as an exception. It is not rare and it does not mean anything is broken.

Absent is not false

This is the single most important sentence on the page. Userinfo builds a flat map, adding each claim only if the scope was granted and only if the underlying value exists. There is no null. There is no "declined" marker. There is no per-claim status.

So these two situations produce byte-identical payloads:

• The person did not approve nationality.
• The person approved nationality and there is no nationality record on their account.

And "nationality" in person === false tells you nothing about the person’s nationality. It tells you the platform did not release a value.

# The absence of a key is the signal. There is nothing else to look for.
curl -s "$UNIFYID_API/v1/userinfo" \
  -H "authorization: Bearer $ACCESS_TOKEN" \
  | jq 'has("age_over_18"), .age_over_18'

The claim names you will actually see

Userinfo uses OIDC names where OIDC has them, so the key is not always the scope code:

Contacts are verified contacts only, and one of each: email releases the primary verified address and phone the primary verified number. An unverified address on the account is not a candidate, and there is no scope that releases every address an account has.