API reference
Users
PUT /v1/subjects/{externalUserId} and GET /v1/subjects/{externalUserId}/status — display names and the sanction status of a user.
A user in your app is a subject at Limenia, identified by your externalUserId. Limenia keeps a user file per app with the display name and the sanction status (see Concepts). Both operations are never refused because of the tenant’s plan or subscription.
PUT /v1/subjects/{externalUserId}
Sets the display name of a user, e.g. after a rename, and/or passes the user’s identifiers for ban evasion across apps (see Identifiers). Optional.
curl -sS -X PUT "$LIMENIA_BASE_URL/v1/subjects/u_112" \
-H "Authorization: Bearer $LIMENIA_API_KEY" -H "Content-Type: application/json" \
-d '{"displayName":"maxi_100"}'Body: displayName (at most 100 characters) and identifiers (see Identifiers). Both are optional, but at least one is required (otherwise 400 validation_failed, field /displayName, code required).
- With
displayNamean unknown user is created asactive, so send a display name only for users you have reported before. WithoutdisplayNamethe stored name stays. - With only
identifiers, an unknown user is created only while ban evasion across apps is on for the tenant; otherwise nothing is written. Identifiers never cause an error.
Response 200 with the status as in GET /v1/subjects/{externalUserId}/status below. Errors: 400, 401, 403 tenant_not_active (the tenant is in onboarding or suspended; nothing is written), 429.
GET /v1/subjects/{externalUserId}/status
Current sanction status of a user. The fallback when a webhook was lost: call it at login or in a periodic reconciliation, not on every request.
{ "externalUserId": "u_112", "status": "suspended", "suspendedUntil": "2026-10-08T08:00:00Z" }status:active,warned,suspendedorbanned;suspendedUntilonly withsuspended.- Unknown users are
active. A suspension whosesuspendedUntilhas passed is reported asactiveat once. - Return it to the app only for the signed-in user. Errors: 401, 429.
Status values
status |
Meaning | Set by |
|---|---|---|
active |
No restriction | default; restore with restoreScope: "account"; the end of a suspension |
warned |
Warned, not restricted | warn_user (if active or the suspension has already ended) |
suspended |
Blocked until suspendedUntil |
suspend_user |
banned |
Blocked permanently | ban_user |
Changes arrive as webhooks: decision.created and, when a suspension ends or a complaint ends a restriction, subject.status_changed (see Webhook events). Encode the externalUserId in the path (encodeURIComponent).