Return Data Model

Overview

Enterprise teams often need more than “who the user is.” They also need to answer: “How was this identity verified, and how much can I trust it?” Hopae Connect returns a structured payload containing normalized user attributes alongside a dedicated hopae_provenance object. This object tells the complete story of the verification: who vouched for the identity, how it was presented, and what checks passed.

Example Responses

// The ID Token focuses on the user and the trust level. It's lightweight and ideal for session management.
{
  "iss": "https://sandbox.connect.hopae.com",
  "aud": "YOUR_CLIENT_ID",
  "sub": "wPqH84Q4pDiE4qWWIfGeMQcoctqYfNVf",
  "acr": "urn:hopae:loa4",
  "amr": ["pin"],
  "hopae_loa": 4,
  "name": "Jane Q. Citizen",
  "given_name": "Jane Quincy",
  "family_name": "Citizen"
  "birthdate": "1992-02-02",
  "missingAttributes": ["phone_number", "address"]
}

UserInfo Payload Structure

Here is a conceptual map of the UserInfo payload. This tree view shows how the data is organized, with a brief explanation for each major component. For detailed field specifications, refer to the Schema Tables that follow this section.

{
  // --- Standard Claims ---
  "sub": "...",                // Who is the user? (The unique ID)
  "name": "...",               // What are their attributes? (Normalized user data)
  "birthdate": "...",          //
  
  // --- Assuarance Data
  "acr": "...",                // How much can I trust this? (The assurance level)
  "hopae_loa": "...",         

  // --- The Verification Story ---
  "hopae_provenance": {
    "presentation": {          // The story of *how* the identity was presented.
      
      // The technology channel used for the interaction.
      "channel": {             
        "type": "...",
        "transport": "..."
      },
      
      // A list of documents presented and verified.
      "credentials": [         
        {
          "type": "...",       // What kind of document is this?
          "issuer": { ... },   // Who vouches for this document?
          "evidence": [ ... ], // What is the proof of its authenticity?
          "claims": { ... }    // Origial raw issuer data field
        }
      ]
    },
    
    // Operational data for the verification event.
    "_metadata": {             
      "verification_id": "...",
      "verified_at": "..."
    }
  }
}

Schema Tables

The following tabs provide a detailed field-by-field reference for the structures outlined above.

These are standard OpenID Connect claims representing the user’s identity.

Field	Type	Required	Notes/Example
`sub`	string	Yes	Pairwise user id
`name`	string	No	Display name
`given_name`	string	No
`family_name`	string	No
`middle_name`	string	No
`nickname`	string	No
`preferred_username`	string	No
`profile`	string	No	URL
`picture`	string	No	URL
`website`	string	No	URL
`gender`	string	No	`female`, `male`, `other`
`birthdate`	string	No	`YYYY-MM-DD`
`zoneinfo`	string	No	IANA time zone
`locale`	string	No	BCP 47 (`en-US`)
`email`	string	No	`user@example.com`
`email_verified`	boolean	No	true/false
`phone_number`	string	No	E.164 (`+1415555…`)
`phone_number_verified`	boolean	No	true/false
`address`	object	No	See Address structure below
`updated_at`	number	No	Unix timestamp
`nationality`	string	No	ISO 3166-1 alpha-2

Address Claim Structure

Field	Type	Notes/Format
`formatted`	string	Multi-line, display-ready
`street_address`	string	Street/house/PO Box
`locality`	string	City
`region`	string	State/Province/Region
`postal_code`	string	ZIP/Postal code
`country`	string	ISO 3166-1 alpha-2

Other Verification Examples

The data model is flexible enough to represent various verification methods. Note that some examples may include the optional claims field to show the raw, source-specific data returned by the issuer before normalization.

Remote eID (Belgium Itsme) — API Verification

This example represents a user verifying their identity through a remote, API-based electronic ID service like Belgium’s Itsme. It includes the optional claims object, which contains the original, non-normalized data from the source.

{
  "sub": "aBcDeFgH12345678iJkLmNoPqRsTuVw",
  "acr": "urn:hopae:loa4",
  "hopae_provenance": {
    "presentation": {
      "channel": { 
        "type": "api", 
        "transport": "internet" 
      },
      "credentials": [{
        "type": "EIDAS:eID_Belgium",
        "issuer": { 
          "id": "did:issuer:eu-eidas-be-itsme", 
          "authority_name": "Itsme (Belgian Mobile ID)" 
        },
        "claims": {
          "voornamen": "Jane Quincy",
          "familienaam": "Citizen",
          "geboortedatum": "1992-02-02",
          "rijksregisternummer": "92.02.02-999.99"
        },
        "evidence": [
          { 
            "type": "api_verification", 
            "verifications": { "eidas_level_high_assured": true } 
          }
        ]
      }]
    },
    "_metadata": { "verification_id": "vrf_api_be_itsme_123" }
  }
}

ePassport (FR) — NFC Verification via Visogo SDK

This scenario shows a user verifying their identity by scanning the chip of their physical French ePassport using a mobile application powered by the Visogo SDK. The phone’s NFC reader is used to communicate directly with the passport chip.

{
  "sub": "xYzAbCdE87654321fGhIjKlMnOpQrSt",
  "acr": "urn:hopae:loa4",
  "hopae_provenance": {
    "presentation": {
      "channel": { 
        "type": "sdk_embedded", 
        "transport": "NFC" 
      },
      "credentials": [{
        "type": "ICAO-9303:ePassport",
        "issuer": { 
          "id": "did:issuer:fr-ants", 
          "authority_name": "Agence Nationale des Titres Sécurisés" 
        },
        "evidence": [
          { 
            "type": "chip_verification", 
            "verifications": { "passive_authentication_valid": true, "chip_authentication_valid": true } 
          }
        ]
      }]
    },
    "_metadata": { "verification_id": "vrf_nfc_fr_visogo_456" }
  }
}

mDL (US‑CA) — Samsung Wallet Remote Presentation

This example shows a user presenting their mobile Driver’s License (mDL) from their Samsung Wallet. The verification happens remotely over the internet, not via NFC or QR.

{
  "sub": "wPqH84Q4pDiE4qWWIfGeMQcoctqYfNVf",
  "acr": "urn:hopae:loa4",
  "hopae_provenance": {
    "presentation": {
      "channel": { 
        "type": "app_wallet", 
        "transport": "internet" 
      },
      "credentials": [{
        "type": "ISO18013-5:mDL",
        "issuer": { 
          "id": "did:issuer:us-ca-dmv", 
          "authority_name": "California DMV" 
        },
        "evidence": [
          { 
            "type": "credential_presentation", 
            "verifications": { "issuer_signature_valid": true } 
          }
        ]
      }]
    },
    "_metadata": { "verification_id": "vrf_mdl_us_samsung_789" }
  }
}

Getting Started

Integrations

Concepts

Return Data Model

Overview

Example Responses

UserInfo Payload Structure

Schema Tables

Address Claim Structure

Other Verification Examples

Next Steps

OIDC Provider

Verification Flow

Getting Started

Integrations

Concepts

​Overview

​Example Responses

​UserInfo Payload Structure

​Schema Tables

​Address Claim Structure

​Other Verification Examples

​Next Steps

OIDC Provider

Verification Flow

Overview

Example Responses

UserInfo Payload Structure

Schema Tables

Address Claim Structure

Other Verification Examples

Next Steps