Client‑Side Human Identification for Mobile¶

Human Identity by Wallarm is a client-side service that verifies whether requests to your applications come from real users or automated tools. It covers web and mobile platforms — this article describes the Mobile Antibot component.

Overview¶

Mobile Antibot is a native SDK (iOS / Android) that verifies device integrity using hardware-backed attestation. It proves that a critical action (e.g., login, checkout) originates from a genuine, untampered application running on a real physical device — not from an emulator, a rooted phone, or a repackaged app binary.

The SDK obtains a short-lived (~30 seconds) token and signs the request body immediately before each protected action. This cycle (getToken() → signRequestBody() → send request) is repeated for every critical operation — the token is not reused across multiple API calls.

Even when the server's verdict is to block the device, the SDK still returns a well-formed JWT with a blocked claim — enforcement happens on your backend or Wallarm Node, not in the SDK.

Depending on your setup, the result can be enforced by Wallarm's modules or by your own backend logic.

Where mobile antibot adds value¶

Native mobile applications face threats that browser-based detection cannot address. Bots run on emulator farms, rooted devices, repackaged app binaries, and scripted API clients that bypass the app entirely.

These threats lead to:

• Account takeover via credential stuffing from emulator farms

• Fake account creation at scale from scripted environments

• Checkout and inventory abuse from automated API clients

• API probing from tampered app binaries

Mobile Antibot solves these problems by verifying the device hardware before the action is processed. Deploy it in your native iOS / Android application to protect high-value actions:

How it works¶

The SDK communicates with the Human Identification Server in two steps: first it requests a challenge, then it submits a hardware attestation proof.

Step-by-step flow¶

1. Challenge
   The SDK sends a challenge request to the Human Identification Server (POST /v1/m/hid/c) with the app ID, device ID, and platform. The server returns a nonce and a key status: new (first time) or existing (returning device).

2. Attestation or key proof

   • New device: the SDK generates a key pair inside the device hardware (Secure Enclave on iOS, StrongBox/TEE on Android). The private key never leaves the hardware. The SDK requests a hardware attestation certificate from the OS and submits it to the server (POST /v1/m/hid/v with type: "attestation").
   • Returning device: the SDK proves it still holds the previously registered private key by signing the challenge nonce (POST /v1/m/hid/v with type: "key_proof"). No full re-attestation needed.

3. Server verification
   The Human Identification Server (hosted and managed by Wallarm) validates the attestation:

   • Android: verifies the certificate chain, parses Key Attestation Extension, checks security level (StrongBox/TEE), bootloader lock status, and nonce.
   • iOS: verifies the App Attest attestation object, validates the AAGUID, and checks the nonce.

4. Token issuance
   On success, the server returns a signed JWT and the SDK makes it available to your code. On failure, the SDK returns an empty token (isPresent = false on Android) or throws a HumanIDError (iOS) so your app can handle it accordingly.

5. Request signing
   The SDK signs the request body of the critical action with the hardware-protected private key. This produces a signature proving the device still holds the key — preventing token theft and replay. Both the token and the signature are attached to the request as headers.

6. Enforce
   How you enforce depends on your setup. If you use a Wallarm Node inline, the token and signature headers are forwarded automatically. If you use your own backend, verify the JWT and optionally the per-request signature.

SDK functions¶

do {
    let token = try await sdk.getToken()
    let signature = try await sdk.signRequestBody(body)
    // ...
} catch {
    switch error {
    case .getTokenFailed(let message):
        logger.error("getToken failed: \(message)")
    case .signRequestBodyFailed(let message):
        logger.error("signRequestBody failed: \(message)")
    case .unknownError(let message):
        logger.error("unexpected SDK error: \(message)")
    }
}

Request headers¶

The SDK attaches two headers to protected API requests:

Platform details¶

Setup¶

Step 1: Get your credentials and SDK¶

Contact sales@wallarm.com to enable Human Identity. Provide the application(s) you plan to protect and the platforms you need (iOS, Android, or both).

The Wallarm team will provide:

• Human Identification Server endpoint: https://mobile.us-hi.wallarm.com

• Application ID — identifies your application in the HIS and links requests to your configuration.

• Mobile SDK package:

  • iOS: XCFramework
  • Android: .aar library

The SDK is provided directly by the Wallarm team during onboarding — it is not available in public package registries.

Supported platforms: iOS 18+ / Android 9+ (API level 28).

Step 2: Add the SDK to your project¶

Step 3: Initialize the SDK and protect critical actions¶

Initialize the SDK once at app startup. Then, before each critical action, call getToken() and signRequestBody() to obtain a fresh token and sign the request. The token is short-lived (~30 seconds) and must not be reused across multiple actions.

import com.wallarm.humanid.HumanIDConfig
import com.wallarm.humanid.HumanIDSDK

// Initialize once at app startup
val config = HumanIDConfig(
    clientIDKey = "YOUR_APP_ID",
    serverUrl = "https://mobile.us-hi.wallarm.com"
)
val session = HumanIDSDK.init(context = applicationContext, config = config)

// Before EACH critical action (e.g., login, checkout):
val token = session.getToken()

if (token.isPresent) {
    val bodyBytes = requestJson.toByteArray()
    val signature = session.signRequestBody(bodyBytes)

    request.addHeader("X-HID-Token", token.value)
    request.addHeader("X-HID-Signature", signature)
}

// Repeat getToken() + signRequestBody() for every critical request

import WallarmHumanIDSDK

// Initialize once at app startup
let config = try HumanIDConfig(
    cloud: .us,
    applicationID: "YOUR_APP_ID"
)
let sdk = HumanIDSDK(config: config)

// Before EACH critical action (e.g., login, checkout):
do {
    let token = try await sdk.getToken()
    let signature = try await sdk.signRequestBody(bodyData)

    request.setValue(token.value, forHTTPHeaderField: "X-HID-Token")
    request.setValue(signature, forHTTPHeaderField: "X-HID-Signature")
} catch {
    // error is typed as HumanIDError — see SDK functions section
}

// Repeat getToken() + signRequestBody() for every critical request

Step 4: Enforce¶

There are 2 approaches — choose based on your infrastructure:

Step 5: Test the integration¶

Verify that tokens are issued correctly:

1. Launch your app on a real device and trigger a protected action.

2. Verify that both X-HID-Token and X-HID-Signature headers are present in the API request.

3. Confirm that token.isPresent == true (Android) or getToken() returns without error (iOS).

4. Test with an emulator — token.isPresent should be false (Android) or getToken() should throw a HumanIDError (iOS).

Verify that enforcement works:

• Wallarm modules: in Wallarm Console → API Sessions, confirm that sessions are grouped by device identifier. Trigger a configured enforcement rule and verify that the session is blocked.

• Your own backend: verify that requests with a valid JWT are accepted and requests without headers are rejected.

Related resources¶

• Human Identification for Web — browser-based verification for web applications

• API Abuse Prevention — server-side behavioral bot detection

Was this page helpful?

How can we improve this article? (Optional)

Information is unclear or confusing

Insufficient information

Outdated or incorrect information

0/240

Send