Custom OIDC Claims

Overview

CLEAR’s Custom OIDC Claims feature introduces a flexible, standards-aligned framework that allows partners to dynamically request and receive custom identity claims directly within OIDC ID tokens and verified_claims structures.

This feature adheres to the OIDC Claims Parameter Specification, supporting both:

Top-level claims
Verified claims via verified_claims.claims

Key Capabilities

Dynamic Claim Injection

Many expressed desire for claims using the OIDC claims parameter. CLEAR dynamically populates allowed claims in the ID token.

Support for Top-Level and Verified Claims Structures

Top-Level Claims: Returned directly at the root of the ID token
Verified Claims: Returned under verified_claims.claims per OIDC Identity Assurance

Scope-Based Claim Mapping

Claims populate based on predefined relationships between OIDC scopes and internal verification attributes.

Verification Outcome Signals in Access Tokens

Access tokens may include:

verification_status
verification_completed_at
verification_failure_reasons
verification_id
verification_is_sandbox

Allowed Claims

"claims_supported": [
  "sub",
  "iss",
  "exp",
  "iat",
  "verification_id",
  "email",
  "email_verified",
  "phone_number",
  "phone_number_verified",
  "ssn4",
  "ssn9",
  "id_number",
  "id_type",
  "gender",
  "document",
  "name",
  "given_name",
  "family_name",
  "middle_name",
  "birthdate",
  "preferred_username",
  "address",
  "ip",
  "amr"
]

Requesting Verified Claims

You may request specific claims at the top level of the ID token using the claims parameter.

Example Claims Request

{
  "id_token": {
    "email": null,
    "phone_number": null,
    "email_verified": null,
    "phone_number_verified": null
  }
}

Example Authorization URL

http://cvBaseUrl/oauth2/auth?response_type=code&
client_id=client-id&
state=testingstate&
redirect_uri=https%3A%2F%2Fjwt.io&
scope=offline%20openid%20offline_access&
claims={%22id_token%22%3A%20{%22email%22%3A%20null%2C%20%22phone_number%22%3A%20null%2C%20%22email_verified%22%3A%20null%2C%20%22phone_number_verified%22%3A%20null}}

Example ID Token (Top-Level Claims)

{
  "email": "[email protected]",
  "phone_number": "+11234567890",
  "email_verified": true,
  "phone_number_verified": true,
  "verification_id": "verify_Qu4Ce34R6x8kb1mkHIfTomXRxK0ic06v",
  ...
}

Requesting Top-Level Claim

You may request verified claims grouped under the verified_claims structure.

Example Claims Request

{
  "id_token": {
    "verified_claims": {
      "claims": {
        "email": null,
        "phone_number": null,
        "email_verified": null,
        "phone_number_verified": null,
        "amr": null
      }
    }
  }
}

Example Authorization URL

http://127.0.0.1:5566/oauth2/auth?response_type=code&
client_id=79bc6622-abbb-4fd6-8668-ae57e012351f&
state=teststate&
redirect_uri=https%3A%2F%2Fjwt.io&
scope=offline%20openid%20offline_access&
claims={%22id_token%22%3A%20{%22verified_claims%22%3A{%22claims%22%3A%20{%22amr%22%3A%20null%2C%20%22phone_number%22%3A%20null%2C%20%22phone_number_verified%22%3Anull}}}}

Example ID Token (Verified Claims)

{
  "verified_claims": {
    "claims": {
      "amr": ["sms"],
      "email_verified": true,
      "email": "[email protected]",
      "phone_number": "+11234567890",
      "phone_number_verified": true
    }
  }
}

Verification Outcomes in Access Tokens

Access tokens also convey verification results.

Successful Verification Example

{
  "verification_status": "success",
  "verification_completed_at": "2025-12-11T17:51:28",
  "verification_id": "verify_XLQU1J3lE5Z84SuN1iTeUDLF7E6bmOTK",
  "verification_is_sandbox": false
}

Failed Verification Example

{
  "verification_status": "fail",
  "verification_failure_reasons": ["authentication_error"],
  "verification_completed_at": null,
  "verification_id": "verify_zjUp0Ca4ykPyG7f6NAHWQAeDb58bOpfl"
}