API reference
Device checks
POST /v1/devices/check — check the device of a user at registration and login with Play Integrity or DeviceCheck.
POST /v1/devices/check
Device connector: your backend forwards a fresh device token at registration and at every login, also at the login of a banned account before rejecting it (only then can Limenia mark the device). Requires a plan with the device connector.
Flow: (1) your backend picks a random nonce and computes requestHash = base64url(SHA-256("limenia:" + externalUserId + ":" + nonce)) without padding for the signed-in user and keeps it a few minutes, single use; (2) the app gets a token with that hash (limenia_device); (3) the app sends platform and token to your backend; (4) your backend sends them with the user from its login and the hash it issued.
curl -sS -X POST "$LIMENIA_BASE_URL/v1/devices/check" \
-H "Authorization: Bearer $LIMENIA_API_KEY" -H "Content-Type: application/json" \
-d '{"externalUserId":"u_112","platform":"test","token":"test:emulator-1","event":"login"}'| Field | Required | Meaning |
|---|---|---|
externalUserId |
yes | 1 to 128 characters, from your login |
platform |
yes | android, ios or test (test mode) |
token |
yes | Android: the integrity token, unchanged and not decoded (a second decode returns cleared verdicts). iOS: Base64 token of DCDevice.generateToken. Test: test:<device> or test:<device>:risk, <device> matching [a-z0-9-]{1,40}. At most 8000 characters. |
requestHash |
no | Android only: the requestHash (standard request) or nonce (classic request) of the token; checked if set. At most 500 characters. |
environment |
no | iOS only: production (default) or development for debug builds |
event |
no | registration, login, report or other (default) |
identifiers |
no | HMACs of the e-mail address and phone number of the user for ban evasion across apps (see Identifiers). Never causes an error. |
Response
Response 200:
{
"checkId": "01K…",
"platform": "android",
"status": "evaluated",
"deviceFlag": "banned",
"flaggedSince": "2026-09",
"deviceAction": "none",
"integrity": { "device": "device", "appRecognized": true, "licensed": true, "risks": ["controlling_apps"], "testingResponse": false },
"subject": { "externalUserId": "u_112", "status": "active" },
"test": false
}status:evaluatedorunevaluated(fail-open: Google or Apple unreachable, quota used up, or 429/5xx from them; thendeviceFlagisunknown).deviceFlag:none,suspended,bannedorunknown(bits not readable). The bits belong to the developer account, so a ban in another app of the same account marks the device too.flaggedSince: month of the marking (YYYY-MM), if known.deviceAction: what Limenia wrote now,none,marked_banned,marked_suspendedorreset.integrity(Android only):device(strong,device,basic,virtual,none,unevaluated),appRecognized,licensed(absent if not evaluated),risks(play_protect_off,play_protect_medium_risk,play_protect_high_risk,capturing_apps,controlling_apps,overlay_apps,high_activity; later versions may add values),testingResponse.subject: the status as inGET /v1/subjects/{externalUserId}/status.test:truefor test tokens.- A marked device is a hint, never proof. Never reject or ban automatically because of
deviceFlag; never reject because ofunevaluatedorunknown. Suggested: ondeviceFlag: bannedat registration, let a rule open a case or restrict the new account provisionally until a moderator decides. - No
Idempotency-Key; never retry with the same token. On network errors, 429 and 5xx treat the result asunevaluatedor get a new token.
Errors
Errors: 400 validation_failed, invalid_device_token (rejected by the provider, wrong package, requestHash mismatch, or token older than 15 minutes; do not retry; common causes: token already decoded, wrong hash, iOS debug build without environment: development); 401; 402 subscription_required; 403 feature_not_in_plan, tenant_not_active; 409 device_connector_not_configured (platform not active for the app, or test without test mode); 429.
Setup, test mode and data protection duties are on the device connector page.