LuxID Partner API
What the Partner API is
The LuxID Partner API is a server-to-server REST API that lets your back-end interact with the LuxID side of your integration without going through a user's browser. While the OpenID Connect (OIDC) and SAML 2.0 flows handle real-time authentication for end users, the Partner API handles everything your operators and back-end systems need to do outside of an active sign-in: provisioning users into groups, reading or revoking subscriptions, attaching custom data to a user, and reading the stream of events that happen across your integration.
It is not the API your customer-facing application calls when a user is signing in - that is the OIDC layer. The Partner API sits one layer behind: it is for your servers talking to LuxID's servers, using client credentials issued to you when your partnership is set up.
When you reach for the Partner API
Some examples of what each capability is for, to help you decide whether you need this API at all:
- You have an internal admin UI that lists who has access to your application, and you want to drive it from a real source of truth rather than rebuilding the view locally - read the Applications and Application Subscriptions capabilities.
- You have role-based access inside your application (e.g. "managers", "auditors", "external partners") and you want LuxID to be that source of truth - use the Groups capability with the bulk-actions endpoint so an HR system or admin console can add and remove members in batches.
- You want to attach a piece of partner-specific data to a user that should flow back into the OIDC ID token next time they sign in - use the Claims capability.
- You want to be notified, or to reconcile, what happens to users across your integration (sign-ins, subscription changes, account events) - poll the Event Hub capability.
If your need does not fit any of these, you probably do not need the Partner API. The OIDC userinfo endpoint and ID token claims cover most day-to-day cases.
The five capabilities at a glance
| Capability | What it does | Read this page |
|---|---|---|
| Applications | Discover which applications and instances LuxID has registered for your partnership. | Applications |
| Application Subscriptions | Read or revoke a user's current subscription to one of your applications. | Application Subscriptions |
| Groups | List your partner-managed groups, list members, list a user's group memberships, and add or remove members in bulk. | Groups |
| Claims | Set or remove a custom claim value on a subscriber, to be surfaced on subsequent authentications. | Claims |
| Event Hub | Search the time-ordered stream of user-related events tied to your applications. | Event Hub |
Each capability page is built around real workflows, with concrete curl examples. The full machine-readable specification is available as a downloadable OpenAPI file.
What to read before your first call
If you have not already read it, start with Getting started with the Partner API. It covers the things that apply to every endpoint: how authentication works, which base URL belongs to which environment, the standard error shape, and the conventions used by the API (path identifiers, MD5-hashed emails for account lookup, etc.).
What the Partner API does not do
A few things the Partner API is not the right tool for, so you do not waste time looking:
- End-user authentication. Users do not sign in through this API - that is OIDC. See Authenticate.
- Creating new LuxID Accounts on behalf of users. Accounts are created by users themselves through the LuxID sign-up flow. The Partner API operates on accounts that already exist.
- Changing a user's profile (email, phone, password, 2FA settings, etc.). Users manage their own profile at account.luxid.lu (opens in a new tab). The Partner API can attach custom claims to a user, but cannot edit identity data the user owns.
- Configuring your application's registration in LuxID (client secrets, redirect URIs, branding, etc.). That is done through the LuxID Console, not this API.
API version
This documentation describes version 1.9 of the Partner API. The version is in the API's info block in the OpenAPI document; breaking changes are communicated alongside new versions when they ship.