LuxID developer documentation
LuxID is a Luxembourgish digital identity provider operated by POST Luxembourg on behalf of a LuxID E.I.G. (Economic Interest Grouping formed by POST Luxembourg, RTL, Cactus, CFL). It is a sovereign identity service that Partners federate to - one shared identity authority used by many services. You do not need to provision a tenant, manage authentication policies, or rotate signing keys on your side: LuxID does the heavy lifting and you integrate via standard protocols.
This documentation explains how to integrate LuxID into a web, mobile, desktop, or backend application using standard OpenID Connect, OAuth 2.0, and SAML 2.0 protocols.
Who this documentation is for
- Developers building a web, mobile, or backend application that signs users in with LuxID.
- IT administrators wiring LuxID into off-the-shelf SaaS tools (Odoo, ServiceNow, WordPress, Microsoft 365, etc.) through configuration rather than code.
- Architects, security and compliance leads evaluating how LuxID fits a target architecture and trust model.
- Designers and product owners wiring up the "Sign in with LuxID" experience.
For end-user help articles (account creation, password reset, 2FA setup), see the user documentation.
How LuxID is structured
LuxID exposes integrators to a small set of concepts:
- Organization - a legal entity in the LuxID ecosystem (POST Luxembourg, RTL, Cactus, CFL, ...). Organizations group all the technical surface that a company uses.
- Partner - the unit of API access. An Organization may hold several Partners (one per subsidiary, business line, or team - for example POST has one Partner for telecom services and another for postal services). The Partner is what holds the client credentials. Partners are created administratively under an Organization once the LuxID Agreement has been signed at the Organization level.
- Application - the concrete software product that integrates LuxID: a website, a mobile app, a kiosk. An Application belongs to exactly one Partner.
- Sphere - a pseudonymisation domain. Applications inside the same Sphere see the same
sub(subject identifier) for a given user. Applications in different Spheres see differentsubvalues, so LuxID never leaks a cross-product user identifier without explicit design intent. - Subscription - a user's connection to an Application. When a user signs in to an Application for the first time and consents to share attributes, a Subscription is created. Revoking it terminates the link.
- Group - an authorisation grouping inside a Partner (and optionally scoped to a specific Application). Used to convey roles or entitlements to the integrating application.
- Claim - an attribute (given name, email, phone, ...) pre-declared on an Application at registration and released after user consent. Unlike vanilla OAuth/OIDC where the client freely requests claims at runtime, LuxID reviews and approves each Application's claim set up front, acting as a privacy guardrail against over-collection.
- Consent - the user's explicit agreement to share a set of Claims with an Application; revocable at any time from the LuxID Account.
A deep walkthrough of this model lives in Concepts and fundamentals.
Supported standards
| Standard | Use cases | Where to look |
|---|---|---|
| OpenID Connect 1.0 | Sign-in to web, mobile, desktop apps; identity assertions | Authenticate / OpenID Connect |
| OAuth 2.0 (RFC 6749) | Delegated access to APIs, machine-to-machine | Authenticate / OAuth2 for APIs |
| SAML 2.0 | Legacy enterprise SSO, SaaS that only speaks SAML | Authenticate / SAML 2.0 |
| OAuth 2.0 PKCE (RFC 7636) | Recommended flow for all public and confidential clients | Add Login |
| WebAuthn / FIDO2 (W3C) | Passwordless and passkeys as MFA | Features / Passwordless and Passkeys |
| eIDAS LoA | Assurance levels (low, substantial, high) | Concepts / Assurance Levels |
The discovery document for the production tenant is available at https://login.luxid.lu/.well-known/openid-configuration (opens in a new tab). The UAT equivalent is at https://login-uat.luxid.lu/.well-known/openid-configuration (opens in a new tab).
LuxID ships features incrementally, so some capabilities described in this documentation may not yet be enabled for your Partner. What you read here describes the target integration contract: how the feature will appear to your integration once available. Features that may be off, restricted, or pilot-only at the time you read this include:
- LuxID Verified - identity-attribute verification via LuxTrust (and the EUDI Wallet in future).
- LuxID Pro - enterprise federation that lets corporate IdPs (Microsoft Entra ID, Google Workspace, Okta, ADFS, Ping, ...) authenticate users into LuxID-enabled services.
- LuxID for OpenRoaming - Wi-Fi federation that lets LuxID-authenticated users roam onto participating OpenRoaming networks.
If a Partner Application hits an endpoint that corresponds to a disabled feature, LuxID returns HTTP 403 with a {"type": "FEATURE_DISABLED", "message": "Feature disabled"} body. See Common errors for the troubleshooting steps.
Integration paths
There are four shapes of integration with LuxID. Pick the one that matches your situation.
- Developer integration (you write the code). Your application directly speaks OIDC, OAuth 2.0, or SAML to LuxID. See Get started and Authenticate.
- Leaf SaaS configuration (no code). You run an off-the-shelf tool (Odoo, WordPress, Drupal, ServiceNow, Atlassian, Microsoft 365, Salesforce, Moodle, ...) and configure LuxID as its identity source. See Quick Integrations.
- Identity broker federation (no code). You run your own identity broker or federation hub (Keycloak, FusionAuth, Synapse/Matrix, ...) for your application stack and configure LuxID upstream as an external identity provider or "Sign in with LuxID" option. Your broker continues to manage your apps; LuxID is one identity source among others. See Identity broker integrations.
- LuxID Pro enterprise federation (corporate single sign-on). Your organisation runs a corporate IdP (Microsoft Entra ID, Google Workspace, Okta, ADFS, Ping, ...) and you want employees to use those corporate credentials when accessing LuxID-enabled services. LuxID delegates authentication to your corporate IdP via OIDC or SAML federation. See LuxID Pro federation.
Documentation map
The documentation is organised in five layers, not as a linear book. See the Mental Model for how to navigate.
| Layer | Sections | Question answered |
|---|---|---|
| Understand | Get started, Concepts | What is LuxID? |
| Integrate | Quick Integrations, Authenticate | How do I wire up sign-in? |
| Design and Trust | UX and branding, Secure | How do I make it recognisable and safe? |
| Enhance | Features, APIs and advanced, Testing and tooling | What extra value can I draw from LuxID? |
| Operate and Comply | LuxID Console, Governance, Troubleshooting | How do I run it in production responsibly? |
Persona entry points
| If you are a... | Start at |
|---|---|
| Backend developer | Get started then Authenticate |
| Frontend / mobile developer | Authenticate / Add Login then UX and branding |
| IT administrator | Quick Integrations |
| Architect | Concepts then Secure |
| Product owner / designer | UX and branding then Features |
| Security or compliance officer | Concepts, Secure, Governance |
| QA / integrator | Testing and tooling |
Where LuxID lives
The user-facing account dashboard is at https://account.luxid.lu/ (opens in a new tab). Integrators register their applications and obtain credentials by following Configure LuxID.
Getting help
- For integration support, contact LuxID.
- See Troubleshooting and support for common errors.
- For quick answers to the questions Partners ask most often, see the Frequently asked questions.