Claims

Nom, type et signification des claims retournés dans l'id_token et userinfo.

Les claims sont fournis dans l’id_token et par userinfo. Le scope demandé détermine quels claims sont concernés (voir les scopes).

Lire les claims : guide pour débuter

Présent, vide ou absent

Un claim peut être dans trois états, et votre code doit les distinguer :

État	Signification	Exemple
Présent avec une valeur	L’utilisateur a partagé cette information et elle est disponible.	`"email": "john.doe@example.com"`
Présent mais vide (`""`)	L’utilisateur a accepté de la partager, mais le credential est en attente de validation (partage différé).	`"private:ssn": ""`
Absent	Scope non demandé, information que l’utilisateur n’a pas fournie, ou credential supprimé. L’opération n’échoue pas pour autant.	pas de clé `phone_number`

Une valeur vide ou absente ne signifie jamais « faux ». Pour un claim vraiment indispensable, utilisez les claims obligatoires.

Le suffixe `_verified` : la confiance qu’on peut accorder

Un claim peut être vérifié (extrait d’un document contrôlé par TrustMe) ou simplement déclaré par l’utilisateur. Le claim *_verified associé le dit :

Claim	Valeurs	Signification
`private:person_verified`	rempli	L’identité de base provient d’un document d’identité officiel vérifié.
`email_verified`, `phone_number_verified`	`true` / `false`	`true` : vérifié par un code à usage unique (OTP).
`private:address_verified`	`document`	Justificatif (avis d’imposition, facture d’énergie ou de téléphone) fourni.
`private:bankaccount_verified`	`openbanking` ou `document`	Acquis auprès de la banque, ou depuis un document de coordonnées bancaires.
`private:ssn_verified`	`document`	Un document portant le numéro a été fourni.

À retenir : le scope profile ne dit pas comment les claims ont été vérifiés. Si votre décision en dépend (KYC, âge légal), demandez plutôt private:person, qui s’appuie sur un document officiel.

Les identifiants

sub est l’identifiant stable de l’utilisateur pour votre service (aléatoire ou anonymisé selon votre configuration, voir Onboarding). Utilisez-le comme clé en base. N’utilisez ni l’e-mail ni le nom, qui peuvent changer ou se répéter.

Formats à connaître

Donnée	Format
`birthdate`	`YYYY-MM-DD`
`gender`	`male` ou `female`
`private:birthcountry`	Code pays ISO 3166 alpha-2 (`fr`)
`private:nationality`	Code pays ISO 3166 alpha-3 (`FRA`)
`phone_number`	International E.164 (`+33612345678`)
`address.formatted`	Sauts de ligne `\n`, norme AFNOR NF Z 10-011
`*.credential.issuance` / `.expiration`	ISO 8601

Attention à l’écart alpha-2 / alpha-3 entre le pays de naissance et la nationalité.

Dates de validité des credentials

Chaque information provient d’un credential conservé dans le wallet de l’utilisateur, avec une durée de vie limitée. *.credential.expiration indique quand il expire, par exemple pour une pièce d’identité ou une adresse. Ne confondez pas cette date avec l’expiration du jeton (exp). Si votre cas d’usage l’exige, refusez ou redemandez une information dont le credential a expiré.

Documents et empreintes

Les claims private:doc.* contiennent une URL, pas le document. Le claim *.hash donne l’empreinte sha256:… de chaque fichier renvoyé par l’API document : comparez-la après téléchargement pour vous assurer que le fichier n’a pas été altéré ou remplacé.

Quels scopes pour quel besoin (à titre indicatif)

Besoin	Scopes à envisager
Ouvrir un compte avec identité vérifiée	`openid` `private:person` `email` `phone` (+ `address`)
Conserver la pièce d’identité	ajouter `private:doc.id` (et `private:doc.photo` pour la photo seule)
Virement, prélèvement	`private:bankaccount`
Dossier social ou santé	`private:ssn.fr` (+ `private:doc.ssn`)
Recevoir des informations en cours de validation	ajouter `private:delayed_sharing`

Chaque scope supplémentaire est une information de plus que l’utilisateur doit accepter de partager, et une donnée de plus que vous devrez protéger : voir la checklist.

Identité de base

Claim	Type	Description
`given_name`	STRING	Tous les prénoms.
`family_name`	STRING	Nom de famille.
`gender`	STRING	`male` ou `female`.
`birthdate`	STRING	Date de naissance, format YYYY-MM-DD.
`private:birthplace`	STRING	Ville de naissance, telle que sur le document officiel.
`private:birthcountry`	STRING	Pays de naissance, code ISO 3166 alpha-2.
`private:birthplace.insee`	STRING	Code INSEE de la ville de naissance. Vide si né hors de France. Partiellement basé sur une saisie utilisateur.
`private:birthcountry.insee`	STRING	Code INSEE du pays de naissance. Disponible si né hors de France. Basé sur une saisie utilisateur.
`private:nationality`	STRING	Nationalité, code ISO 3166 alpha-3.
`private:married_name`	STRING	Nom d’usage.

Autres claims

Claim	Type	Description
`email`	STRING	Adresse e-mail.
`email_verified`	BOOLEAN	Vérifiée par défi OTP.
`phone_number`	STRING	Numéro au format international E.164.
`phone_number_verified`	BOOLEAN	Vérifié par défi OTP.
`address`	OBJECT	Claim `address` standard OIDC. Séparateur de `formatted` : saut de ligne `\n`, format AFNOR NF Z 10-011.
`private:address_details`	OBJECT	`format` (norme de `formatted`), `street_number`, `street`.
`private:address_verified`	STRING	`document` : l’utilisateur a fourni un avis d’imposition ou une facture (énergie, téléphone).
`private:bankaccount`	OBJECT	`bank`, `bic`, `iban`, et `rib` (banque française : `bank_code`, `counter_code`, `account_number`, `key`).
`private:bankaccount_verified`	STRING	`openbanking` (acquis auprès de la banque) ou `document` (document de coordonnées bancaires).
`private:ssn`	STRING	Numéro de sécurité sociale.
`private:ssn_key`	STRING	Clé de contrôle du numéro de sécurité sociale.
`private:ssn_verified`	STRING	`document` : un document portant le numéro a été fourni.

Claims de documents

Claim	Type	Description
`private:doc.id`	STRING	URL de l’API pour récupérer la pièce d’identité (vérifiée).
`private:doc.photo`	STRING	URL de la photo d’identité, accessible avec un access token.
`private:doc.address`	STRING	URL du justificatif d’adresse vérifié.
`private:doc.bankaccount`	STRING	URL du document de coordonnées bancaires vérifié.
`private:doc.ssn`	STRING	URL du document de sécurité sociale vérifié.
`private:doc.id.hash`	array(STRING)	Empreintes du contenu de chaque document retourné par l’API document (`sha256:...`).
`private:doc.photo.hash`	array(STRING)	Idem pour la photo.
`private:doc.address.hash`	array(STRING)	Idem pour le justificatif d’adresse.
`private:doc.bankaccount.hash`	array(STRING)	Idem pour les coordonnées bancaires.
`private:doc.ssn.hash`	array(STRING)	Idem pour le document de sécurité sociale.

Dates des credentials

Les claims proviennent de credentials gérés par le wallet de l’utilisateur, vérifiés avant tout partage. Chaque credential a une durée de vie limitée ; ces claims donnent ses dates d’émission et d’expiration.

Claim	Type	Description
`private:person.credential.issuance`	STRING	Date d'émission du credential d'où les claims `person` sont extraits (ISO 8601).
`private:person.credential.expiration`	STRING	Date d'expiration de ce credential (ISO 8601).
`private:email.credential.issuance`	STRING	Date d'émission du credential d'où les claims `email` sont extraits (ISO 8601).
`private:email.credential.expiration`	STRING	Date d'expiration de ce credential (ISO 8601).
`private:phone_number.credential.issuance`	STRING	Date d'émission du credential d'où les claims `phone_number` sont extraits (ISO 8601).
`private:phone_number.credential.expiration`	STRING	Date d'expiration de ce credential (ISO 8601).
`private:address.credential.issuance`	STRING	Date d'émission du credential d'où les claims `address` sont extraits (ISO 8601).
`private:address.credential.expiration`	STRING	Date d'expiration de ce credential (ISO 8601).
`private:bankaccount.credential.issuance`	STRING	Date d'émission du credential d'où les claims `bankaccount` sont extraits (ISO 8601).
`private:bankaccount.credential.expiration`	STRING	Date d'expiration de ce credential (ISO 8601).
`private:ssn.credential.issuance`	STRING	Date d'émission du credential d'où les claims `ssn` sont extraits (ISO 8601).
`private:ssn.credential.expiration`	STRING	Date d'expiration de ce credential (ISO 8601).
`private:photo.credential.issuance`	STRING	Date d'émission du credential d'où les claims `photo` sont extraits (ISO 8601).
`private:photo.credential.expiration`	STRING	Date d'expiration de ce credential (ISO 8601).