Application Subscriptions

What a Subscription is

A subscription is the link between one of your applications and one LuxID Account. It is created the first time the user authenticates against your application through LuxID and consents to share their data, and it is the record you can later inspect to know that "yes, this user is currently a customer/member of this application of mine".

A subscription is identified by three things: the application (applicationExtId), the subscriber (the user, either subscriberExtId or the MD5 hash of their email), and the beginDate recording when the link started.

This capability lets you do three things:

What you want to do	Endpoint
Get the current subscription for one (application, subscriber-id) pair	GET /applications/{applicationExtId}/subscriptions/{subscriberExtId}/current
Get the current subscription for one (application, email) pair	GET /accounts/{md5HashOfLowercaseEmail}/applications/{applicationExtId}/subscriptions
Revoke a subscription (the user is no longer linked to this application)	DELETE /applications/{applicationExtId}/subscriptions/{subscriberExtId}/current

There is no "create subscription" endpoint - subscriptions are created automatically when a user signs in to your application for the first time. The Partner API only lets you read or revoke an existing one.

Look up by subscriber id

If you already have the subscriberExtId (typically retrieved from an earlier event or stored on your side after the user's first sign-in), use the path-id variant:

curl -sS \
  -H "X-Client-Id: $LUXID_CLIENT_ID" \
  -H "X-Client-Secret: $LUXID_CLIENT_SECRET" \
  https://api-uat.luxid.lu/services/luxid-partner-api/applications/app-abc-123/subscriptions/sub-user-42/current

Response:

{
  "subscriberExtId": "sub-user-42",
  "applicationExtId": "app-abc-123",
  "beginDate": "2026-01-15T09:23:11Z"
}

Look up by email

If you only have the user's email (e.g. an admin is troubleshooting "does this person have access to MyApp?"), use the email variant.

attention

Send the MD5 hash of the lowercased email, never the raw email, exactly as described in Getting Started.

EMAIL_HASH=$(echo -n "alice@example.com" | tr 'A-Z' 'a-z' | md5sum | awk '{print $1}')

curl -sS \
  -H "X-Client-Id: $LUXID_CLIENT_ID" \
  -H "X-Client-Secret: $LUXID_CLIENT_SECRET" \
  "https://api-uat.luxid.lu/services/luxid-partner-api/accounts/$EMAIL_HASH/applications/app-abc-123/subscriptions"

The response shape is identical to the subscriber-id variant.

Revoke a Subscription

Deleting a subscription removes the link between the user and your application. The user's LuxID Account is untouched; they simply no longer have an active subscription to your application. If they sign in again later, a fresh subscription is created.

curl -sS -X DELETE \
  -H "X-Client-Id: $LUXID_CLIENT_ID" \
  -H "X-Client-Secret: $LUXID_CLIENT_SECRET" \
  https://api-uat.luxid.lu/services/luxid-partner-api/applications/app-abc-123/subscriptions/sub-user-42/current

Response:

{
  "removalDate": "2026-05-18T13:45:02Z"
}

The removalDate tells you when LuxID actually severed the link, which may be different from the moment you called (some changes propagate asynchronously). Use this value if you need an audit record on your side.

When to revoke

Common reasons partners revoke a subscription from the Partner API:

• Off-boarding from your service. The user cancelled their account on your side; you no longer want them to retain a "current subscriber" record on LuxID's side.
• Compliance / right-to-be-forgotten. A user's right-to-erasure request requires the link between their LuxID Account and your application to be removed. (Note: the LuxID Account itself is the user's to delete via account.luxid.lu (opens in a new tab); revoking the subscription only affects the partner-side link.)
• Reconciliation after an internal migration. You moved a user to a different application within your partnership; revoke the old subscription so reports stay clean.

astuce

If you only want to temporarily disable access for a user (rather than remove the link entirely), revoking is the wrong tool. Use the Groups capability to remove the user from an access-granting group, and handle the actual gate inside your application logic.

Errors you may see

Status	When	What to do
400	The request was malformed or violated a business rule (e.g. the user has no subscription to delete).	Read message.
403	The application is not yours, or the subscriber is not visible to your partnership.	Confirm the applicationExtId belongs to you (cross-check with the Applications listing).
404	The application, subscriber, or subscription does not exist.	Verify the path identifiers; for the email variant, recompute the MD5 hash (lowercase, trimmed).

Typical use cases

• An off-boarding hook. When a user cancels on your side, fire a DELETE to clean up the LuxID-side subscription so it does not stay visible in user-facing "connected applications" lists at account.luxid.lu (opens in a new tab).
• A support tool. Internal support agents enter a user's email; you hash it client-side, call the email-lookup endpoint, and display whether the user is currently subscribed and since when.
• Periodic reconciliation. Once a day, your back-end iterates the users you believe are subscribed and verifies LuxID agrees. Diverging entries get reconciled.