# UserInfo and claims

Truora Pass releases all identity information through a single endpoint: `GET /v1/oauth2/userinfo`. Treat the tokens your application receives as opaque credentials — do not try to decode or verify them locally. To read the user's identity, call the UserInfo endpoint with the access token; Truora Pass is the verifier and answers with exactly the claims the user consented to share.

## Calling the UserInfo endpoint

Send a `GET` request to the UserInfo endpoint with the access token as a Bearer token:

```bash
curl --request GET 'https://api.pass.truora.com/v1/oauth2/userinfo' \
  --header 'Authorization: Bearer <access_token>'
```

The response is a dynamic JSON map: which keys appear depends on the scopes granted to the access token. The `sub` claim (the stable user identifier for your application) is always present. Claims without data are omitted — for example, the `profile` claims are only included when the corresponding field is non-empty.

Example response for an access token granted the `openid email profile` scopes:

```json
{
  "sub": "WLT_USR_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "email": "ana@example.com",
  "email_verified": true,
  "name": "Ana García",
  "first_name": "Ana",
  "last_name": "García",
  "birthdate": "1992-04-15",
  "nationality": "CO",
  "updated_at": 1719945600
}
```

**Note**: when the `background` scope is granted, Truora Pass refreshes the user's background information before building the response, so the returned `trust_level` reflects the latest available result.

## Claims by scope

The table below lists every claim the UserInfo endpoint can release, grouped by the scope that unlocks it. See the [Scopes reference](/truora-pass/scopes_reference/) for what each scope means and how to request it.

| Scope | Claims |
|---|---|
| `openid` | `sub` — stable user identifier (always present in every response) |
| `email` | `email`, `email_verified` (boolean) |
| `phone` | `phone_number`, `phone_number_verified` (boolean) |
| `profile` | `name`, `first_name`, `last_name`, `gender`, `birthdate` (`YYYY-MM-DD`), `nationality`, `updated_at` (Unix timestamp, integer) — each included only when non-empty |
| `identity` | `identity_verified` (boolean), `verification_level` (`basic` or `none`), `given_name`, `family_name`, `birthdate`, `nationality`, `document_number`, `document_type`, `issuing_authority`, `is_risky` (boolean), `was_manually_reviewed` (boolean); `document_expired` (boolean) and `expiration_date` only when the document is verified and expired |
| `documents` | `documents` — array of `{document_type, document_number, country, date_of_birth}` objects (valid documents only; `date_of_birth` when available) |
| `age` | `age_verified` (boolean); when a birthdate is on file: `is_minor` (boolean), `age_range` (`under_18`, `over_18`, `over_21`, or `over_65`), `birthdate` |
| `address` | `address` — object `{country, street_address, city, state_province, postal_code, address_verified}` |
| `background` | `trust_level` (`high`, `medium`, `low`, or `not_available`), `background_verified` (boolean), `verification_badges` (array), `manual_verification_status` |
| `biometric` | `face_enrolled` (boolean), `last_face_verification_date` (RFC 3339, when available), `liveness_check_passed` (boolean), `face_match_confidence` (`not_available`), `quality_level` (`not_available`), `verification_method` (`photo`) |
| `verification` | `verification_status` (`full`, `partial`, or `none`), `verification_date` (RFC 3339, when available), `verification_methods` — array with any of `document`, `face` |
| `contact` | `email`, `email_verified`, `phone_number`, `phone_number_verified`, `preferred_communication_method` (`email`) |
| `nationality` | `nationality` |

**Note**: The two name conventions are intentional, not a typo. The `profile` scope releases the user's self-reported profile as `first_name` / `last_name` (plus the combined `name`), while the `identity` scope releases the document-verified name under the OpenID Connect standard claims `given_name` / `family_name`. When both scopes are granted, the response contains both sets.

For guidance on interpreting the verification-related claims (`identity_verified`, `verification_status`, `trust_level`, and friends), see [Consuming identity-verification results](/truora-pass/verification_results/).

## The ID token

When the granted scopes include `openid`, the token response from the [Authorization Code flow](/truora-pass/authorization_code_flow/) or the [CIBA flow](/truora-pass/ciba_flow/) also contains an `id_token`. The ID token is a record of the authentication event, not a carrier of identity data — it contains only the fixed OpenID Connect claims:

| Claim | Meaning |
|---|---|
| `sub` | User identifier (same value as UserInfo `sub`) |
| `iss` | Issuer |
| `aud` | Your `client_id` |
| `iat` | Issued-at time |
| `exp` | Expiration time |
| `auth_time` | When the user authenticated (when available) |
| `amr` | Authentication methods used (when available) |
| `acr` | Authentication context class satisfied (when available) |

Key facts about the ID token:

1. It expires **5 minutes** after issuance — use it at sign-in time, then rely on the access token.
2. It is issued only when the `openid` scope is granted.
3. It is **not** re-issued when you refresh the access token with a [refresh token](/truora-pass/refresh_tokens/).
4. It never contains scope-derived identity claims. All identity data — name, documents, verification status — is released exclusively by the UserInfo endpoint.

**Note**: treat both the access token and the ID token as opaque values. Do not attempt local signature verification; read the user's identity by calling `GET /v1/oauth2/userinfo`.

## Error responses

| HTTP status | Error | When |
|---|---|---|
| 401 | Missing or invalid Bearer token | The `Authorization` header is absent, malformed, or the token is invalid or expired |
| 401 | `insufficient_scope` — "Invalid token: missing scopes" | The token carries no usable scopes |
| 404 | `user_not_found` | The user behind the token no longer exists |

See [Errors and troubleshooting](/truora-pass/errors_and_troubleshooting/) for the full error catalog across all endpoints.