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.

Shell
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:

JSON
{
  "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: evaluated or unevaluated (fail-open: Google or Apple unreachable, quota used up, or 429/5xx from them; then deviceFlag is unknown).
  • deviceFlag: none, suspended, banned or unknown (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_suspended or reset.
  • 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 in GET /v1/subjects/{externalUserId}/status. test: true for test tokens.
  • A marked device is a hint, never proof. Never reject or ban automatically because of deviceFlag; never reject because of unevaluated or unknown. Suggested: on deviceFlag: banned at 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 as unevaluated or 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.