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.

Shell
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 displayName an unknown user is created as active, so send a display name only for users you have reported before. Without displayName the 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.

JSON
{ "externalUserId": "u_112", "status": "suspended", "suspendedUntil": "2026-10-08T08:00:00Z" }
  • status: active, warned, suspended or banned; suspendedUntil only with suspended.
  • Unknown users are active. A suspension whose suspendedUntil has passed is reported as active at 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).