Claims

What claims are for

A claim in this capability is a key-value pair you attach to a subscriber. The next time the user authenticates against your application, LuxID surfaces the value in the OIDC layer (typically in the ID token or via the userinfo endpoint), provided the claim is part of your Application's Claim Template. Claim release is governed by the Claim Template, not by the scope parameter. This is how your partnership feeds partner-specific data into LuxID without owning the user's profile.

Technical claims, not consent-based user claims

The claims managed through this API are technical claims: they are invisible to the user and require no consent. They carry partner-supplied data - for example a partner-side identifier (such as a chat or Matrix ID) that the Partner's own application cannot conveniently store itself, so it is parked on the LuxID subscriber and returned on each sign-in. They are distinct from user claims - the consent-based profile attributes the user controls (name, email, phone, and the enriched attributes in Attribute enrichment). You do not set user claims through this API; you set technical claims that LuxID then surfaces back to your own application.

Concretely, claims are useful when:

• Your application needs to know the user's internal customer number in your system, and you want LuxID to carry it back to you on every sign-in rather than running a lookup each time.
• You enrich a user's profile with a partner-specific role or tier (e.g. "gold-customer", "compliance-officer") that should travel with the OIDC token rather than being re-derived in the application.
• You need to stamp a user with metadata when a back-office event occurs (a contract upgrade, a flag set by your compliance team) so that downstream sign-ins see the new value automatically.

Claims set through the Partner API are partner-scoped and subscriber-scoped: the value is attached to one specific subscriber (a user in the context of your application), not to the underlying LuxID Account globally. Two applications under the same partnership can hold different claim values for the same end-user, because each application sees the user through its own subscriber record.

The endpoints in this capability are:

What you want to do	Endpoint
Set or replace a claim value on a subscriber	PUT /subscribers/{subscriberExtId}/claims/{claimName}
Remove a claim from a subscriber	DELETE /subscribers/{subscriberExtId}/claims/{claimName}

note

There is no GET for claims through the Partner API: the value comes back to your application through OIDC on the user's next authentication. If you need to inspect what is currently set, your back-end should also store the value locally when it issues the PUT.

Set a claim value

curl -sS -X PUT \
  -H "X-Client-Id: $LUXID_CLIENT_ID" \
  -H "X-Client-Secret: $LUXID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "value": "gold-customer" }' \
  https://api-uat.luxid.lu/services/luxid-partner-api/subscribers/sub-user-42/claims/customer-tier

Response (empty object):

{}

caution

If a claim with this name was already set on this subscriber, the new value replaces the old one. There is no merge semantics: a PUT is a full overwrite. If you need multi-valued claims, encode the list yourself (e.g. comma-separated, JSON-encoded) and parse it on the receiving end.

The claim name (customer-tier in the example) must match a claim that has been registered for your partnership in LuxID. Trying to set a claim name that has not been registered returns a 404. Claim registration happens during onboarding or through your LuxID Account manager; it is not self-service in the Partner API.

Real claim names are prefixed

Partner-specific claims are provisioned with the naming convention luxid_<partner-prefix>_<name> (for example luxid_examplecorp_membership_id), not the bare attribute name. The generic customer-tier above is illustrative - confirm the exact registered claim name with LuxID.

End-to-end: from email to claim

If you only have the user's email (not their subscriberExtId), the full flow is two calls. First resolve the subscriberExtId from the email, then set the claim.

# 1. Resolve subscriberExtId from the user's email.
#    Send the MD5 hash of the lowercased email, never the raw address.
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/my-application/subscriptions"
# -> returns { "subscriberExtId": "sub-user-42", "applicationExtId": "my-application", ... }

# 2. Set the partner-specific claim on that subscriber.
curl -sS -X PUT \
  -H "X-Client-Id: $LUXID_CLIENT_ID" \
  -H "X-Client-Secret: $LUXID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "value": "M-00482915" }' \
  https://api-uat.luxid.lu/services/luxid-partner-api/subscribers/sub-user-42/claims/luxid_examplecorp_membership_id

The value appears in the user's ID token (or UserInfo response) on their next authentication, provided the claim is declared in your Application's Claim Template. For the email-lookup details and the applicationExtId, see Application Subscriptions and Getting Started.

Remove a claim

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/subscribers/sub-user-42/claims/customer-tier

Response (empty object):

{}

After a successful DELETE, the next OIDC token issued to this subscriber will not carry the claim. Existing already-issued tokens still carry whatever value they were issued with - the change applies to subsequent authentications, not to live sessions.

When the change becomes visible to your Application

Claims set or removed through the Partner API are reflected on the next authentication that produces a new ID token or a new userinfo response. They do not invalidate live sessions or already-issued tokens. If your application needs the new value to apply immediately, your application has to re-trigger an authentication (e.g. by forcing a refresh or by calling the userinfo endpoint).

If your application caches tokens, factor in the OIDC token lifetimes you have configured: a short ID-token lifetime means claim changes propagate quickly; a long one means they may lag by hours.

Errors you may see

Status	When	What to do
400	Request body is missing or malformed (e.g. missing value).	Send a body of the shape { "value": "..." }.
403	The subscriber is not visible to your partnership, or the claim name is registered but not editable by your partnership.	Confirm the subscriberExtId is yours; confirm the claim name with your account manager.
404	The subscriber does not exist, or the claim name is not registered for your partnership.	Verify both identifiers.

Typical use cases

• A "VIP" flag that follows the user. Your CRM determines that a user is now a VIP. Your back-end issues a PUT .../claims/vip with value "true". The user's next sign-in delivers the flag to your application, which renders the VIP UI without an extra database lookup.
• A customer reference number that lives outside your auth code path. Your billing system holds the customer number; the user's application back-end does not. Set it as a claim, and your front-end logic reads it from the OIDC token rather than calling the billing API on every page load.
• Compliance tagging. When your compliance team flags a user (e.g. needs additional verification), set a claim. The application gates the feature based on the claim's presence and value, and clears the gate by removing the claim once the requirement is satisfied.

What claims are not

• Not the user's profile. Email, name, phone, addresses, etc. live on the LuxID Account and are managed by the user. Claims are partner-side annotations on the partner-side subscriber, not edits to the LuxID Account.
• Not authentication settings. You cannot set 2FA preferences, password rules, or session controls via claims.
• Not a generic key-value store. Each claim name has to be registered, and the value is plumbed through the OIDC flow. If you need arbitrary data tied to a user, store it on your side and key by subscriberExtId.