Technical Documentation
itsme verification data: capture and downstream sharing
What identity data itsme provides, where Unidy stores it, and how it reaches downstream apps like Roboticket.
What itsme provides
On a successful itsme authentication, Unidy receives an OIDC ID token with:
- Standard claims:
sub,given_name,family_name,name,birthdate,gender,email/email_verified,phone_number,address.
- itsme KYC claims (legally verified):
http://itsme.services/v2/claim/BENationalNumber(Belgian national-register number),.../BEeidSn, citizenship, ID-document metadata, and similar.
Where Unidy stores it
- Identity link: a
SocialLoginrow withprovider = openid_connectanduid = <itsme sub>. A unique index on(provider, uid)guarantees one itsme identity maps to exactly one Unidy account.
- Profile fields: claim mappings copy itsme claims onto standard user fields (first/last name, date of birth, address, phone).
- KYC extras: claims with no standard field (for example the national number) are stored as custom attributes via
custom:mappings.
- Verification state:
users.verified_atis the single source of truth, stamped on every verification (itsme login, post-login connect, or manual admin verification). Theverifiedflag is derived from it (present and within the 1-year window) - there is no storedverifiedcustom attribute.
How it flows downstream (to Roboticket)
Unidy acts as the OIDC provider for downstream apps. Verification data is exposed through OAuth claims (admin-configured):
- A claim exposing
verifiedlets the app gate access on identity verification.
- A claim exposing
verified_atgives the app the verification timestamp, so it can enforce its own 1-year window.
- Any mapped KYC fields / custom attributes can likewise be exposed as claims.
The downstream app receives these in the ID token / userinfo response, keyed to the stable subject user.unidy_id.
Gating: adding verified to the app's required fields blocks unverified users from connecting and redirects them to Unidy to verify (see the itsme setup guide).
Data lifecycle and freshness
verified_atis refreshed on each (re)verification, by any source.
- A daily job expires verifications older than 1 year: it clears
verified_at, and becauseverifiedis derived, the flag flips to false automatically - so the downstream app immediately sees the fan as unverified until they re-verify.
- Because
verified_atis a single "most recent verification" timestamp, re-verifying through any path (itsme or manual) refreshes it uniformly.
No-email fans
If itsme shares no email, Unidy assigns a synthetic <uuid>@kyc.invalid placeholder and requires the fan to add a real email (double opt-in). Until that email is confirmed, the email claim shared downstream is the synthetic placeholder. See itsme integration: how it works (Technical Documentation > Single Sign-on) for the full flow.
Privacy note
The Belgian national-register number and other KYC claims are sensitive. They are only stored and shared if you explicitly map them (claim mappings) and expose them (OAuth claims). Map and expose only what the downstream integration actually needs.