Choosing claims
Twenty-one scopes, three risk tiers, and the difference between a ceiling and a grant.
The ceiling and the grant
Two separate ideas, and most confusion about this platform comes from collapsing them.
The ceiling is allowedClaimScopes on your application record: what this application may ever request. The grant is what one person approved on one consent screen. A scope must clear the ceiling to be requested and clear the grant to be released.
An authorization request is checked three times before the screen is even drawn:
- The scope must exist in the catalogue. If it does not, the request fails with
invalid_scope. - The scope must be in the application's
allowedClaimScopes.openid,profile,emailandidentity_verifiedare an always-allowed baseline. Verified identity is required in every application configuration and is added to every authorization request. A returning person whose previous grant did not include it must approve the additional permission before it is released. - A restricted scope requires Production review before live use. Sandbox access is limited to eligible testers and application-scoped test identities.
The twenty-one scopes
The complete catalogue as the API exports it, with the risk tier that governs each scope
| Scope | Category | Risk | What it releases |
|---|---|---|---|
| openid | Authentication | standard | Confirm the person’s identity using a pairwise subject identifier. |
| profile | Authentication | standard | Access the approved basic profile bundle. |
| Contact | standard | Access the primary verified email address on the account. | |
| phone | Contact | standard | Access the primary verified phone number on the account. |
| legal_name | Personal identity | sensitive | Access the verified legal name. |
| age | Personal identity | sensitive | Access the current verified age. |
| age_over_18 | Personal identity | standard | Confirm whether the person is at least 18 without sharing their birth date. |
| date_of_birth | Personal identity | restricted | Access the verified complete date of birth. |
| nationality | Personal identity | sensitive | Access verified nationalities approved by the user. |
| identity_verified | Identity assurance | standard | Confirm that UnifyID has verified the person. |
| identity_assurance_level | Identity assurance | standard | Access the assurance level reached by the identity. |
| profile_photo_comparison | Identity assurance | restricted | Compare photos you upload to this application with your enrolled face. |
| identity_documents | Documents | sensitive | List user-approved verified document summaries. |
| document_type | Documents | standard | Access the type of an approved identity document. |
| document_issuing_country | Documents | standard | Access the issuing country of an approved document. |
| document_expiry_date | Documents | sensitive | Access the expiry date of an approved document. |
| document_validity | Documents | standard | Access whether an approved document is active, expired, or revoked. |
| document_verified | Documents | standard | Confirm that an approved document passed verification. |
| document_verified_at | Documents | sensitive | Access when an approved document was verified. |
| profile_photo | Personal identity | restricted | Access the verified profile picture, as a link the application reads with its own token. |
| document_number_masked | Documents | sensitive | Access only the masked identifier of an approved document. |
What the three tiers cost you
standard- Nothing beyond the ceiling and the person's approval. Eleven of the twenty-one.
sensitive- Nothing extra at the gate either. The tier changes how the claim is treated and presented, not whether you may ask.
restricted- A production-active application, plus a written justification of at least 20 characters per restricted scope, which staff read as part of the production review. Today three scopes are restricted:
date_of_birthandprofile_photo_comparisonandprofile_photo.
Restricted scopes can be exercised by eligible testers and test identities in Sandbox. Production use requires review and a stated purpose. Prefer age or age_over_18 when a full birth date is unnecessary. profile_photo shares a verified picture; profile_photo_comparison permits a separate comparison of a proposed photo, with simulated results in Sandbox. See Profile picture and Profile photo comparison.
What gets read at read time
On every call to userinfo, the effective scopes are the token's scopes intersected with the consent in force. If the person disconnects, an old access token stops answering.
What this does not do
- There are no required and optional claims. Every scope you send is part of one decision. There is no flag that marks a claim as nice-to-have, and nothing in the platform will hand you a partial approval because you marked one that way.
- A granted scope is not a delivered value.
nationalitygranted on an account with no nationality record releases nothing at all — see Handling the callback. - Document scopes on their own release no document. They also need a document policy on the application. See Identity documents.
Verified against API commit 234dba22 on 2026-10-18. The routes, scopes, checklist, events and limits on these pages are read from that export, not typed.