Roles in the ecosystem
Overview
Integrating with LuxID requires a shared vocabulary. This page defines every entity in the LuxID domain model, explains the relationships between them, and works through concrete examples that show how these concepts affect your integration decisions - particularly around user identity stability, pseudonymisation, and authorisation.
Read this page before writing integration code. The concepts here inform every other page in the developer documentation.
The entity model at a glance
The diagram below shows the full entity model. The sections below define each entity in depth.
The user
A User is a person who holds a LuxID Account. The User is the subject of every authentication and identity assertion LuxID produces.
Identifier: The User's LuxID identifier is their email address. This is the address they registered with and the one that appears in the email claim. LuxID previously supported usernames; that mechanism is legacy and not promoted. Applications should treat the email address as the human-readable identifier and sub as the stable programmatic identifier (see Subscriptions below for why sub is Sphere-scoped).
What LuxID knows about the User: LuxID uses a progressive profile model. At registration the User only provides an email address and a password - that is the entire required identity. Every other attribute is optional and added later, either when the User decides to fill it in from their LuxID Account, or when a Partner Application prompts for it and the User agrees: phone number, gender, date of birth, postal address, and the verified attributes that come from completing LuxID Verified (identity proofing via LuxTrust). Applications receive only the attributes the User holds and has explicitly consented to release - a claim is absent rather than empty when the User never provided that data.
What LuxID does not store: As a rule, LuxID does not store application-specific user data - that is your application's responsibility. LuxID provides identity; your application provides the service. The deliberate exception is a technical claim: a small piece of partner-supplied data (for example a partner-side identifier) that LuxID can hold on the subscriber and return on each sign-in, for cases where your application cannot conveniently store it itself. It is an exception for that narrow need, not a general-purpose data store - see Partner API - Claims.
The Organisation
An Organisation is the top-level legal entity that sponsors one or more LuxID Partner relationships. Examples: POST Luxembourg, RTL, Cactus, CFL, ...
The Organisation is a conceptual grouping. It is visible with LuxID and used for governance purposes (contracting, billing, compliance reporting), but it is not yet a first-class object in the LuxID API. Applications do not interact with Organisations directly; they interact with Partners.
One Organisation can have multiple Partners - for example, POST Luxembourg might have separate Partners for its B2C consumer services and its B2B enterprise services, each with distinct client credentials and Sphere configurations.
The Partner
A Partner is the unit of API access. It is the entity that:
- holds Partner API credentials (
X-Client-IdandX-Client-Secret, used as request headers - distinct from the OIDCclient_id/client_secretthat each Application holds for the user-facing sign-in flow), - is registered with LuxID with an agreed Claim Template (the set of claims its Applications may receive),
- manages zero or more Applications, and
- may have rights on zero or more Groups for authorisation.
When LuxID documentation refers to a "LuxID Partner", it means an Organisation that has signed the LuxID Agreement and been onboarded - not a generic business partner in the non-technical sense.
Multiple Partners per Organisation: A large Organisation may operate several Partners to maintain separation of concerns. For example:
- POST B2C Partner: owns MyPost, MyPost Telecom apps; Sphere
POST-B2C. - POST B2B Partner: owns DCC, MySOC apps; Sphere
POST-B2B.
Each Partner has its own client_id. Partners are each associated with one or more Spheres (and a Sphere can in turn be shared with another Partner - see Spheres). Users signing into POST B2C apps and POST B2B apps will see different sub values because those apps belong to different Spheres.
The Application
An Application is a concrete software product - a website, a mobile app, a kiosk, a backend service - that a User interacts with. An Application is managed by zero or one Partner: the Partner that registered it normally retains management rights, but those rights can be removed, leaving the Application without an active managing Partner.
In OIDC/OAuth 2.0 terms, an Application is a Relying Party (RP) or Client. It initiates the authorisation flow, receives tokens, and uses those tokens to make decisions about the authenticated User.
Every Application is registered with LuxID with:
- Identity metadata - a display name and logo (shown on the LuxID consent screen), a short description, the public URL of the service, and a technical and administrative contact,
- Protocol - OIDC, OAuth 2.0, or SAML,
- Allowed redirect URIs (OIDC/OAuth 2.0) or Assertion Consumer Service URLs (SAML), validated by exact-match at runtime,
- The Claim Template it is associated with - which determines the claims released, regardless of the
scopeparameter the client sends. See Tokens and Claims - Requesting claims. - The Sphere it belongs to,
- Access rules (optional) - any minimum
auth_level, Guard rules, or User rules to evaluate at sign-in.
An Application cannot change its Sphere after registration. The Sphere assignment is a trust and privacy decision made at onboarding time.
Per-environment registrations
UAT and Production are completely independent environments. The same Application (for example, "RTL Play Web") exists as a separate registration in each environment, with its own Client ID, Client Secret, redirect URIs, and lifecycle. A credential issued in UAT does not work in Production, and vice versa. See Environments for the promotion workflow.
The Sphere
The Sphere is LuxID's pseudonymisation domain: Applications in the same Sphere share the same
subfor a given User, and no global user identifier crosses Sphere boundaries.
It is the most important concept for data privacy in the LuxID model.
What a Sphere does
Every Application belongs to exactly one Sphere. LuxID generates a sub (subject identifier) that is unique per User per Sphere. This means:
- Applications in the same Sphere see the same
subfor a given User. - Applications in different Spheres see different
subvalues for the same User.
LuxID does not expose a global user identifier. A Partner who knows a User's sub in Sphere A cannot use that value to look up the User's identity in Sphere B. Cross-Sphere correlation is not possible through the standard API.
Worked example
Consider the following Sphere configuration:
| Partner | Sphere | Applications in Sphere |
|---|---|---|
| RTL | RTL | RTL.lu, RTL Play |
| POST B2C | POST-B2C | MyPost, MyPost Telecom |
| POST B2B | POST-B2B | DCC, MySOC |
A user - call her Marie - signs into RTL.lu and RTL Play. Both applications receive sub = "rtl-sphere-uuid-for-marie". RTL can correlate Marie's activity across its own products.
Marie also signs into MyPost. MyPost receives sub = "post-b2c-sphere-uuid-for-marie" - a completely different value. RTL cannot use the sub it holds to identify Marie in any POST application, and vice versa. LuxID enforces this isolation; it is not a convention that Partners can opt out of.
Marie also signs into DCC (a POST B2B app). Because POST B2B is a separate Sphere from POST B2C, Marie's sub in DCC is "post-b2b-sphere-uuid-for-marie" - different from both the RTL and POST B2C values.
sub A, sub B, and sub C are entirely distinct UUIDs. No party can derive one from another.
Spheres can be shared between Partners
Although an Application belongs to exactly one Sphere, a Sphere is not locked to a single Partner. A Sphere can be associated with multiple Partners when those Partners need consistent user identifiers across their respective Applications.
Example: POST Luxembourg and POST Telecom are separate Partners (separate API access units, separate client_id values) but share a single Sphere. A user who signs into a POST Luxembourg Application and a POST Telecom Application receives the same sub in both, enabling coordinated account management across the two services. This is an intentional configuration choice - it does not weaken the privacy guarantees the Sphere model provides, because the Partners involved have a declared, agreed reason to share the pseudonymisation domain.
Sphere-sharing is configured at onboarding time by LuxID. Partners cannot unilaterally associate their Applications with another Partner's Sphere.
Sphere design decisions
The Partner decides Sphere boundaries at onboarding time. The key question is: which of your applications need to correlate user activity?
- Applications that must share a user identity (e.g. a website and its companion mobile app) should be in the same Sphere.
- Applications that serve different business units, audiences, or legal entities with distinct data processing purposes should be in separate Spheres.
- Partners that have a declared cross-organisational reason to share identifiers (e.g. two Partners serving the same customer base under different brands) can share a Sphere - but this must be agreed with LuxID at onboarding.
Sphere boundaries are a privacy and governance decision as much as a technical one. Discuss them with your data protection officer before finalising your LuxID onboarding configuration.
The Subscription
A Subscription is the record of a User's connection to an Application. It is created the first time a User completes the consent screen for an Application and terminates when the User revokes that connection from https://account.luxid.lu/ (opens in a new tab).
Subscription and sub stability
The sub value a User sees in a given Sphere is tied to their active Subscriptions in that Sphere:
- While the User has at least one active Subscription in the Sphere: the
subis stable. Even if the User revokes one Application and later re-subscribes, they receive the samesubbecause other Subscriptions in the Sphere keep the Sphere association alive. - When the User revokes their last Subscription in a Sphere: the Sphere association is broken. If the User returns and subscribes again, LuxID allocates a new
sub. This is intentional - it prevents cross-time tracking of users who have explicitly severed all connections within a Sphere.
Do not treat sub as a permanent, eternal user identifier. It is stable as long as the Subscription exists, but revocation followed by re-subscription in a vacated Sphere will produce a new sub. Design your user record storage to handle this: store the sub as a foreign key but be prepared to create a new user record if an unknown sub arrives for a flow that looks like a returning user.
What a Subscription contains
The Subscription record in LuxID captures:
- which User and which Application are connected,
- which claims were consented to and when,
- the timestamp of first connection and last activity.
Partners do not directly query Subscription records. The Subscription's existence is implicit in whether LuxID will issue tokens for a given User/Application pair.
The Group
A Group is an authorisation grouping that Partners use to implement role-based access control without maintaining a separate user directory.
Groups are cross-Sphere
A Group is not tied to a Sphere. A Group can protect Applications that live in any Sphere, including Applications in Spheres other than the one the managing Partner is primarily associated with. The Group is scoped to the Partner that manages it (i.e. holds rights on it), not to a Sphere.
This means a single Group definition can span Applications across multiple Spheres, provided those Applications are under the protection of that Group.
How Groups protect Applications
An Application can be protected by one or several Groups. Protection follows a logical OR: a User can access the Application if they are a member of any of the protecting Groups - membership in all Groups is not required.
If no Groups protect an Application, access is not restricted at the Group level (other access controls such as consent and Subscription still apply).
How Groups work
A Partner's administrators define Groups with LuxID (e.g. admin, editor, premium-subscriber) and assign them to protect one or more Applications.
There are two ways to put a User in a Group:
- By a Partner administrator with LuxID, against the User directly.
- Programmatically, via the Partner API - for adding or removing Group memberships in bulk. The calling Partner must be a manager of the target Group.
When a User authenticates and LuxID issues an ID Token, the token includes the User's Group memberships relevant to that Application.
The Application reads the Group claim and makes access decisions accordingly.
Partner rights on Groups
A Partner may have rights to manage zero or more Groups. "Managing" a Group means the Partner's administrators can create it, edit its membership, and assign it to protect Applications. A Partner does not need to be in the same Sphere as the Applications a Group protects.
Groups vs claims
Groups convey roles (what the user is permitted to do in your application). Claims convey attributes (who the user is). Do not conflate them:
email,given_name,phone_number- these are claims, facts about the user asserted by LuxID.admin,premium-subscriber- these are Groups, role assignments managed by the Partner.
The Claim Template and consent
Claim Template
A Claim Template is a declared data requirement: an Application's statement that it needs a particular attribute from the User. Partners declare Claim Templates at onboarding time. Common examples:
| Claim | Standard | Typical use |
|---|---|---|
given_name | OIDC Core | Personalisation |
family_name | OIDC Core | Personalisation, legal identity |
email | OIDC Core | Account creation, notifications |
phone_number | OIDC Core | SMS contact, 2FA out-of-band |
birthdate | OIDC Core | Age verification |
age_over_16 | LuxID extension | Age-gated content (privacy-preserving). Not currently offered |
Requesting a claim does not guarantee it will be present in the token. The User must consent to each claim individually, and some claims (e.g. birthdate) require the User to have completed identity verification.
Consent
Consent is the User's explicit agreement to release specific claims from their LuxID profile to a specific Application. LuxID presents a consent screen the first time a User encounters an Application that requests claims beyond openid (which is always required and not individually consented - it identifies the authentication event).
The consent screen lists each requested claim by its human-readable label and the purpose declared in the Claim Template. The User may accept or decline individual claims if the Application has marked them as optional.
Consent is revocable: the User can withdraw consent from any Application at any time via https://account.luxid.lu/ (opens in a new tab). Revocation terminates the Subscription and removes LuxID's authorisation to issue tokens carrying those claims for that User/Application pair. The next authentication attempt will re-present the consent screen.
Consent is re-triggered: if a Partner adds new Claim Templates to an Application (requesting claims not previously consented), the consent screen is re-presented to Users on their next authentication, even if they had previously consented to the original set.
Optional Partner-defined checkboxes on the consent screen
Although strictly speaking they are not "consent for claim release", LuxID lets a Partner attach additional acceptance checkboxes to the same consent screen. These are optional and configured per Application:
- Terms and Conditions acceptance for the Partner's service.
- Other explicit consents that are not required to deliver the service - typical example: "I agree that my email may be used to send newsletter and marketing communications", which a Partner may need under GDPR Article 7 (opens in a new tab) for processing distinct from contract performance.
Two consequences for the integrator:
- The user's decision on these checkboxes is captured by LuxID alongside the claim consent. It is versioned: when the Partner updates a T&C document to a new version, LuxID re-presents the consent screen on the user's next sign-in and the user must re-accept before the flow completes. The old acceptance does not transfer to the new version.
- Your application should not duplicate these checkboxes inside its own UI - keep them on the LuxID consent screen so the user only sees them once and the acceptance is stored authoritatively with LuxID.
See Privacy and consent for the full consent lifecycle and GDPR implications.
Federation and LuxID Pro
Federation is a trust relationship that allows users from an external identity system to authenticate with LuxID without creating a separate LuxID credential.
LuxID Pro
LuxID Pro is LuxID's enterprise federation service. It is designed for Organisations whose employees or members already authenticate via a corporate IdP (e.g. Microsoft Entra ID, Okta, an on-premises ADFS). With LuxID Pro:
- The Organisation's corporate IdP is registered as a trusted identity source in LuxID.
- Users who sign in and whose email domain matches the Organisation's federation configuration are redirected to the corporate IdP for authentication.
- The corporate IdP authenticates the user and returns an assertion to LuxID.
- LuxID maps the assertion to a LuxID Account (creating one if necessary) and issues standard OIDC tokens to the Partner's Application.
From the Application's perspective, the flow is identical to a direct LuxID authentication. The Application receives the same token structure, the same claim catalogue, and the same sub (Sphere-scoped). The federation is transparent at the protocol level.
Access restrictions
An Organisation using LuxID Pro may configure LuxID to restrict access to specific Applications to federated users only. This allows an Organisation to gate enterprise applications behind corporate IdP authentication without building a separate access control layer.
What this means for Application developers
If your Partner is configured for LuxID Pro, you do not need to change your integration code. The federation happens within LuxID's authentication layer.
You should be aware of LuxID Pro for support and debugging purposes: if a federated user reports an authentication failure, the root cause may be in the corporate IdP rather than in LuxID or your application.
Entity relationship summary
| Entity | Owned / managed by | Key attribute | Developer-facing? |
|---|---|---|---|
| Organisation | LuxID E.I.G. / Partner contract | Legal entity name | No |
| Partner | Organisation | Partner API credentials (X-Client-Id, X-Client-Secret) | Yes - server-to-server auth |
| Application | Zero or one Partner | OIDC client_id and client_secret (for the Authorization Code + PKCE flow), redirect URIs, Sphere, per-environment registration | Yes - registered config |
| Sphere | Shared configuration (one or more Partners) | Pseudonymisation domain; can be shared between Partners | Implicit in sub |
| Subscription | User + Application | Consent timestamp | Implicit in token issuance |
| Group | Partner (rights on a Group; Group itself is cross-Sphere) | Role name, member list, Applications protected (OR logic) | Yes - in ID Token claims |
| Claim Template | Application | Attribute name, purpose | Yes - in scopes/claims |
| Consent | User + Claim Template | Granted/revoked timestamp | Implicit in claims returned |
| Federation | Organisation | Trusted IdP, domain match | Transparent to app code |
Next steps
- Authentication levels - LuxID's
auth_levelscale, how it maps to eIDAS LoA tiers, and how to request a specific level viaacr_values. - Tokens and claims - the full claim catalogue and how to validate the tokens LuxID issues.
- Privacy and consent - the consent lifecycle and your obligations as a LuxID Partner.
- Add Login - practical integration guide.