Claims

Name, type and meaning of the claims returned in the id_token and userinfo.

Claims are provided in the id_token and by userinfo. The requested scope determines which claims apply (see the scopes).

Reading claims: a beginner’s guide

Present, empty or absent

A claim can be in three states, and your code must tell them apart:

State	Meaning	Example
Present with a value	The user shared this information and it is available.	`"email": "john.doe@example.com"`
Present but empty (`""`)	The user agreed to share it, but the credential is waiting for validation (delayed sharing).	`"private:ssn": ""`
Absent	Scope not requested, information the user did not provide, or credential deleted. The operation does not fail because of it.	no `phone_number` key

An empty or absent value never means “false”. For a truly indispensable claim, use mandatory claims.

The `_verified` suffix: how much to trust a claim

A claim may be verified (extracted from a document checked by TrustMe) or simply declared by the user. The associated *_verified claim tells you:

Claim	Values	Meaning
`private:person_verified`	filled	Base identity comes from a verified official identity document.
`email_verified`, `phone_number_verified`	`true` / `false`	`true`: verified with a one-time code (OTP).
`private:address_verified`	`document`	A proof (tax notice, energy or phone bill) was provided.
`private:bankaccount_verified`	`openbanking` or `document`	Obtained from the bank, or from a bank details document.
`private:ssn_verified`	`document`	A document carrying the number was provided.

Keep in mind: the profile scope does not say how claims were verified. If your decision depends on it (KYC, legal age), request private:person instead, which relies on an official document.

Identifiers

sub is the user’s stable identifier for your service (random or anonymized depending on your configuration, see Onboarding). Use it as your database key. Do not use email or name, which can change or repeat.

Formats to know

Data	Format
`birthdate`	`YYYY-MM-DD`
`gender`	`male` or `female`
`private:birthcountry`	ISO 3166 alpha-2 country code (`fr`)
`private:nationality`	ISO 3166 alpha-3 country code (`FRA`)
`phone_number`	International E.164 (`+33612345678`)
`address.formatted`	`\n` line breaks, AFNOR NF Z 10-011 standard
`*.credential.issuance` / `.expiration`	ISO 8601

Mind the alpha-2 / alpha-3 difference between birth country and nationality.

Credential validity dates

Each piece of information comes from a credential kept in the user’s wallet, with a limited lifetime. *.credential.expiration tells when it expires, for example for an identity document or an address. Do not confuse it with the token expiration (exp). If your use case requires it, refuse or re-request information whose credential has expired.

Documents and digests

The private:doc.* claims contain a URL, not the document. The *.hash claim gives the sha256:… digest of each file returned by the document API: compare it after download to make sure the file was not altered or replaced.

Which scopes for which need (indicative)

Need	Scopes to consider
Open an account with verified identity	`openid` `private:person` `email` `phone` (+ `address`)
Keep the identity document	add `private:doc.id` (and `private:doc.photo` for the photo alone)
Transfer, direct debit	`private:bankaccount`
Social or health file	`private:ssn.fr` (+ `private:doc.ssn`)
Receive information still being validated	add `private:delayed_sharing`

Every extra scope is one more piece of information the user must agree to share, and one more piece of data you must protect: see the checklist.

Base identity

Claim	Type	Description
`given_name`	STRING	All first names.
`family_name`	STRING	Last name.
`gender`	STRING	`male` or `female`.
`birthdate`	STRING	Date of birth, format YYYY-MM-DD.
`private:birthplace`	STRING	City of birth as found on the official id.
`private:birthcountry`	STRING	Country of birth, ISO 3166 alpha-2 code.
`private:birthplace.insee`	STRING	INSEE code of the birthplace. No value when born outside France. Partially based on user input.
`private:birthcountry.insee`	STRING	INSEE code of the country of birth. Available when born outside France. Based on user input.
`private:nationality`	STRING	Nationality, ISO 3166 alpha-3 code.
`private:married_name`	STRING	Married name (nom d’usage).

Other claims

Claim	Type	Description
`email`	STRING	Email address.
`email_verified`	BOOLEAN	Verified with an OTP challenge.
`phone_number`	STRING	Phone number in international E.164 format.
`phone_number_verified`	BOOLEAN	Verified with an OTP challenge.
`address`	OBJECT	Standard OIDC `address` claim. `formatted` separator is a line feed `\n`, AFNOR NF Z 10-011 format.
`private:address_details`	OBJECT	`format` (standard of `formatted`), `street_number`, `street`.
`private:address_verified`	STRING	`document`: the user provided a tax assessment or a utility (energy/phone) invoice.
`private:bankaccount`	OBJECT	`bank`, `bic`, `iban`, and `rib` (French bank: `bank_code`, `counter_code`, `account_number`, `key`).
`private:bankaccount_verified`	STRING	`openbanking` (acquired from the bank) or `document` (banking details document).
`private:ssn`	STRING	Social security number.
`private:ssn_key`	STRING	Social security number control key.
`private:ssn_verified`	STRING	`document`: a document with the number was provided.

Document claims

Claim	Type	Description
`private:doc.id`	STRING	API URL to fetch the id document (verified).
`private:doc.photo`	STRING	URL of the id photo, accessible with an access token.
`private:doc.address`	STRING	URL of the verified address document.
`private:doc.bankaccount`	STRING	URL of the verified banking details document.
`private:doc.ssn`	STRING	URL of the verified social security document.
`private:doc.id.hash`	array(STRING)	Content hashes of each document returned by the document API (`sha256:...`).
`private:doc.photo.hash`	array(STRING)	Same for the photo.
`private:doc.address.hash`	array(STRING)	Same for the address document.
`private:doc.bankaccount.hash`	array(STRING)	Same for the banking details.
`private:doc.ssn.hash`	array(STRING)	Same for the social security document.

Credential dates

Claims come from credentials managed by the user’s wallet, verified before any sharing. Each credential has a limited lifetime; these claims give its issuance and expiration dates.

Claim	Type	Description
`private:person.credential.issuance`	STRING	Issuance date of the credential the `person` claims were extracted from (ISO 8601).
`private:person.credential.expiration`	STRING	Expiration date of that credential (ISO 8601).
`private:email.credential.issuance`	STRING	Issuance date of the credential the `email` claims were extracted from (ISO 8601).
`private:email.credential.expiration`	STRING	Expiration date of that credential (ISO 8601).
`private:phone_number.credential.issuance`	STRING	Issuance date of the credential the `phone_number` claims were extracted from (ISO 8601).
`private:phone_number.credential.expiration`	STRING	Expiration date of that credential (ISO 8601).
`private:address.credential.issuance`	STRING	Issuance date of the credential the `address` claims were extracted from (ISO 8601).
`private:address.credential.expiration`	STRING	Expiration date of that credential (ISO 8601).
`private:bankaccount.credential.issuance`	STRING	Issuance date of the credential the `bankaccount` claims were extracted from (ISO 8601).
`private:bankaccount.credential.expiration`	STRING	Expiration date of that credential (ISO 8601).
`private:ssn.credential.issuance`	STRING	Issuance date of the credential the `ssn` claims were extracted from (ISO 8601).
`private:ssn.credential.expiration`	STRING	Expiration date of that credential (ISO 8601).
`private:photo.credential.issuance`	STRING	Issuance date of the credential the `photo` claims were extracted from (ISO 8601).
`private:photo.credential.expiration`	STRING	Expiration date of that credential (ISO 8601).