How it works — Numira for Developers

How “Login with Numira” works

Decentralized SSO (dSSO) is a standard OpenID Connect flow with one inversion: the identity provider is the user’s own wallet, not a central directory. This page explains what that changes, how aliases work, and exactly where you and the user each make decisions.

1. dSSO vs. traditional SSO

	Traditional SSO (Google / Microsoft)	Decentralized SSO (Numira)
Identity provider	A central directory that sees every login.	The user’s own wallet — no central party observes your logins.
User id (sub)	One global account id, the same across all apps (correlatable).	A different, unlinkable alias DID per app.
What the app learns	Whatever the provider profile exposes.	Only what the user discloses for that login.
Where data lives	On the provider’s servers.	On the user’s device (their wallet).
Choosing identity	One identity; the user can’t segment it per app.	The user picks which alias answers each app.
Revocation	The provider / an admin controls access.	The holder revokes the connection themselves.
Trust / federation	Everyone trusts the central IdP.	DID resolution + issuer registry; no central IdP.

2. Aliases — the core idea

A Numira holder has many aliases — separate, unlinkable per‑context identities, each with its own DID (e.g. a “work” alias, a “social” alias, a “government” alias). They cannot be correlated to each other.

When a user signs in to your app, they present one alias. That alias DID becomes the sub in the id_token.
It is stable for your app (the same user presents the same alias each time → a durable account key) but different at every other app (so no two services can link the same person).
There is no central directory to enumerate or look users up — you only learn about a user when they choose to sign in to you.

3. Where you set what your app can access

Each app you register has a Requested claims list (the allowedClaimsfield on Register app and on each app’s detail page). This is the maximum your app can ever ask a user for.

Empty = login only — you receive just the alias sub, no personal attributes.
List specific keys (e.g. fullName, tier) to request those attributes.
The gateway enforces data minimization: even if the user’s credential holds more fields, only your requested claims are returned, and internal fields (credential ids, commitments) are never released. Request the least you need — it’s also an Acceptable‑Use requirement.

You declare the maximum here; the user grants the actual in their wallet. Setting a claim as “requested” does not guarantee you receive it — the user still approves each disclosure at login.

4. The consent journey — who consents, where, and when

Your app → gateway. You redirect the user to /authorize with your client_id + PKCE. (No user data yet.)
Gateway builds the request. It creates a login request that names your app and lists your requested claims, and shows a wallet QR / deep link.
consent · alias choice The user picks an alias. In Numira, the user scans and the wallet asks which alias to use for your app — never auto‑guessed.
consent · disclosure The user approves what’s shared.The wallet shows “Sign in to <your app> — requesting: <claims>”. The chosen alias’s per‑field disclosure policy applies — each field can be set to share always, share only on consent, share as a proof only (e.g. “over 18” without the date of birth), or never. The user confirms.
Wallet presents. The wallet signs the presentation as the chosen alias, disclosing only the approved claims.
Gateway → your app. You get an authorization code; your backend exchanges it for an id_token whose sub is the alias DID and whose claims are exactly what the user disclosed.
later The user can revoke the connection in their wallet at any time; the gateway then refuses further messages for that alias↔app link.

5. The user chooses the alias — per app

The alias choice belongs to the user and is made in the wallet at each login. Because the sub is a per‑app alias, you get a durable account key for your app while the user stays uncorrelatable across services. You never see the user’s other aliases, their legal identity, or any attribute they didn’t disclose.

Build steps + endpoints: integration manual. Your responsibilities (no re‑identification / correlation, data minimization): legal.