> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopae.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UserInfo

> Returns the verified claims and match outcome, and on request the provenance and missing claims. Requires a valid Bearer access token.

Fetch the verification result using the access token from `/token`. With `hopae`/`idv`, the response follows the same data model as [Get Verification UserInfo](/v2/api-reference/verifications/get-verification-userinfo) on the REST API.

<Info>
  The ID token contains no personal data. `user`, `provenance`, `match`, and `missing_claims` are only returned here, and only when the authorization request included the `hopae` (or `idv`) scope. With `openid` alone you receive `sub`, the available LoA fields, and `verification_model`. `provenance` (which carries the connection identity) and `missing_claims` are also opt-in per request: add `provenance=true` and `missing_claims=true`.
</Info>

## Headers

<ParamField header="Authorization" type="string" required default="Bearer eyJhbGci...">
  Bearer access token issued by `/token` (valid for 10 minutes).
</ParamField>

## Query Parameters

Send these on the query string of a `GET`, or in the form body of a `POST`.

<ParamField query="provenance" type="boolean" default="false">
  `true` (or `1`) adds the `provenance` block, including the connection identity under `provenance._metadata`. Omitted or any other value leaves it out.
</ParamField>

<ParamField query="missing_claims" type="boolean" default="false">
  `true` (or `1`) adds the `missing_claims` list. Omitted or any other value leaves it out.
</ParamField>

## Response

OIDC filters fields by the granted scopes. Unlike REST, it does not expose a top-level `error`. Assurance failures are available under `provenance._metadata.error`.

Connection identity appears only under `provenance._metadata`, never as top-level userinfo fields, so request `provenance=true` to read it. The IDs are snapshotted when the session is created.

<ResponseField name="sub" type="string" required>The verification id. A new value for every verification. Use `user.source_id` to recognise a returning person.</ResponseField>
<ResponseField name="acr" type="string">Authentication Context Class Reference, present when the provider asserted a LoA.</ResponseField>
<ResponseField name="hopae_loa" type="number">Numeric [Level of Assurance](/v2/guides/verifications/assurance).</ResponseField>
<ResponseField name="hopae_loa_label" type="string">Human-readable label (e.g. `substantial`).</ResponseField>
<ResponseField name="provenance._metadata.provider_id" type="string">The provider of the connection that ran, as a catalog provider id (e.g. `smart-id`).</ResponseField>
<ResponseField name="provenance._metadata.connection_id" type="string">The catalog connection id (e.g. `google-wallet-us-mdl`). Opaque. Read `provider_id` and `credential_id` for its parts.</ResponseField>
<ResponseField name="provenance._metadata.credential_id" type="string">The credential that was verified (e.g. `us-mdl`). Requires the `hopae` scope.</ResponseField>
<ResponseField name="provenance._metadata.connection_instance_id" type="string">The activated connection instance the session ran on (`conn_…`). Requires the `hopae` scope.</ResponseField>
<ResponseField name="verification_model" type="string">`disclosure` or `match`.</ResponseField>
<ResponseField name="missing_claims" type="string[]">Returned only with `missing_claims=true`. Requested claims the source could not provide (including `source_id` when it could not be derived).</ResponseField>
<ResponseField name="user" type="object">Verified attributes limited to the workflow's requested claims. For `match`, the verified subset of the values you submitted. See [Normalized User Data](/v2/guides/verifications/normalized-user-data).</ResponseField>
<ResponseField name="match" type="object">Match envelope (`matched`, `granularity`, `submitted_fields`, `details`). Present only for `match` connections.</ResponseField>
<ResponseField name="provenance" type="object">Returned only with `provenance=true`. What the source returned: `presentation.credentials[]` (each with the provider's raw `claims` and, when issued, `evidence`) and `_metadata`. See [Return Data Model](/v2/guides/verifications/return-data-model).</ResponseField>
<ResponseField name="provenance._metadata.error" type="object">Present only when the verification finished with a lower LoA than requested (`code: "loa_insufficient"`).</ResponseField>

<Note>
  Workflow decision nodes add their outputs here (`metLoa`, `hasClaim`, `computed.*`). Dynamic `evaluate` outputs that are not on the OIDC claims whitelist are only available through the REST userinfo endpoint.
</Note>

## Example

<RequestExample>
  ```bash theme={null}
  curl -X GET 'https://connect.hopae.com/v2/userinfo?provenance=true&missing_claims=true' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'
  ```
</RequestExample>

<ResponseExample>
  ```json Disclosure (provenance=true&missing_claims=true) theme={null}
  {
    "user": {
      "given_name": "OK",
      "family_name": "TESTNUMBER",
      "name": "OK TESTNUMBER",
      "birthdate": "1905-04-04",
      "nationality": "LT",
      "source_id": "PNOLT-40504040001"
    },
    "missing_claims": [
      "email"
    ],
    "acr": "urn:hopae:loa:4",
    "hopae_loa": 4,
    "hopae_loa_label": "high",
    "verification_model": "disclosure",
    "provenance": {
      "presentation": {
        "credentials": [
          {
            "claims": {
              "documentNumber": "PNOLT-40504040001-MOCK-Q",
              "birthdate": "1905-04-04",
              "countryCode": "LT",
              "givenName": "OK",
              "surname": "TESTNUMBER"
            },
            "evidence": {
              "token": {
                "id_token": "<BASE64_ID_TOKEN>",
                "expires_at": "2026-09-03T10:19:52.000Z",
                "access_token": "<OPAQUE_ACCESS_TOKEN>",
                "token_type": "Bearer"
              },
              "names": "id_token;expires_at;access_token;token_type"
            }
          }
        ]
      },
      "_metadata": {
        "verification_id": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
        "verified_at": "2026-09-03T09:19:52.110Z",
        "status": "completed",
        "provider_id": "smart-id",
        "connection_id": "smart-id",
        "credential_id": "smart-id",
        "connection_instance_id": "conn_01J8XK2P4M9QR3TV"
      }
    },
    "sub": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8"
  }
  ```

  ```json openid scope only theme={null}
  {
    "sub": "019bc4f2-8a31-7c5e-9d02-4f7a1b3e60d8",
    "acr": "urn:hopae:loa:4",
    "hopae_loa": 4,
    "hopae_loa_label": "high",
    "verification_model": "disclosure"
  }
  ```
</ResponseExample>

## Errors

| HTTP | When |
| :- | :- |
| 401 `invalid_token` | The access token is missing, expired (10 minutes), or is not valid for this OIDC provider |
| 403 `AUTH_DATA_PROTECTED` | The authorization request used `private_mode=true` |


## OpenAPI

````yaml GET /userinfo
openapi: 3.1.0
info:
  title: Hopae Connect OpenID Provider
  version: 2.0.0
servers:
  - url: https://connect.hopae.com/v2
    description: Hopae Connect
security: []
tags:
  - name: OIDC
paths:
  /userinfo:
    get:
      tags:
        - OIDC
      summary: UserInfo
      operationId: userinfo
      parameters:
        - name: provenance
          in: query
          required: false
          description: >-
            `true` (or `1`) adds the `provenance` block, including the
            connection identity under `provenance._metadata`. Off by default. On
            `POST /userinfo`, send it in the form body.
          schema:
            type: boolean
            default: false
        - name: missing_claims
          in: query
          required: false
          description: >-
            `true` (or `1`) adds the `missing_claims` list. Off by default. On
            `POST /userinfo`, send it in the form body.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Verified data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '401':
          description: >-
            `invalid_token`: the access token is missing, expired, or from
            another mode.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
              example:
                error: invalid_token
                error_description: the access token is missing, expired, or from another mode.
        '403':
          description: >-
            `AUTH_DATA_PROTECTED`: user data cannot be released for this
            session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
              example:
                error: AUTH_DATA_PROTECTED
                error_description: user data cannot be released for this session.
      security:
        - bearerAuth: []
components:
  schemas:
    UserInfo:
      type: object
      properties:
        user:
          type: object
          description: >-
            Verified attributes, limited to the claims the workflow requested.
            `source_id` appears only when selected in the workflow and the
            source provided it. See [Normalized User
            Data](/v2/guides/verifications/normalized-user-data).
          additionalProperties: true
        missing_claims:
          type: array
          items:
            type: string
          description: >-
            Returned only with `missing_claims=true`. Requested claims the
            source could not provide (may include `source_id`).
        acr:
          type: string
          description: Authentication Context Class Reference.
        hopae_loa:
          type: number
          description: Numeric Level of Assurance, 1 to 5.
        hopae_loa_label:
          type: string
          description: LoA label.
        verification_model:
          type: string
          description: '`disclosure` or `match`.'
          enum:
            - disclosure
            - match
        match:
          type: object
          description: >-
            Match outcome: `matched`, `granularity`, `submitted_fields`,
            `details`. Match connections only.
        error:
          type: object
          description: >-
            Present when the achieved LoA was lower than requested
            (`loa_insufficient`).
        provenance:
          type: object
          description: >-
            Returned only with `provenance=true`. What the source returned, plus
            verification metadata. See [Return Data
            Model](/v2/guides/verifications/return-data-model).
          properties:
            presentation:
              type: object
              description: >-
                `credentials[]`, one entry per credential the source presented,
                each with the source's own `claims` as received and, when
                issued, `evidence`.
            _metadata:
              type: object
              description: >-
                Metadata about the verification and the connection that ran.
                These ids are not repeated at the top level.
              properties:
                verification_id:
                  type: string
                  description: The verification id. Same value as `sub`.
                verified_at:
                  type: string
                  format: date-time
                  description: When the verification completed.
                status:
                  type: string
                  description: Verification status when the result was read.
                error:
                  type: object
                  description: >-
                    Only when the verification ended with an error (for example
                    `loa_insufficient`).
                provider_id:
                  type: string
                  description: >-
                    Catalog provider id of the connection that ran (for example
                    `smart-id`).
                connection_id:
                  type: string
                  description: >-
                    Catalog connection id. Human-readable but opaque: read
                    `provider_id` and `credential_id` instead of parsing it.
                credential_id:
                  type: string
                  description: Catalog credential id of the connection that ran.
                connection_instance_id:
                  type: string
                  description: >-
                    Your app's activated instance of the connection, the id the
                    verification was started with (`conn_…`).
        sub:
          type: string
          description: >-
            The verification id. New for every verification, so it is not a
            stable user identifier. Use `user.source_id` to recognise a
            returning person. Always the last key.
    OAuthError:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Access token from `/token`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.