HumanDetect™ Token Verification

Once you’ve received a token generated by the SDK and sent it to your backend servers, the next step is to verify it to check the result.

What Is Verification?

Token verification is handled by the Token Verification API, and has a few responsibilities:

  1. Verify token authenticity, ensuring it’s genuinely produced by our SDK.
  2. Return valid, where true means human and false means bot.
  3. Return the identifier you provided, allowing you to perform additional logic.

The identifier is a value you provide in the SDK, and can be used to identify the user, act as a nonce, or be any other value you’d like to securely verify in your backend.

Verify the Token

Token verification happens through a request from your backend to our API. While the SDK Key you used previously works with the SDK, a separate, private API Key is needed for the API. Learn more about using the API and making authenticated calls.

To verify the token, POST it to the /v1/humandetect/verify endpoint:

$ curl https://api.unify.id/v1/humandetect/verify \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $SERVER_API_KEY" \
  --request POST \
  --data '{"token":"token-generated-by-the-sdk"}'

The response is a JSON object that summarizes the token:

{
  "valid": true,
  "identifier": "your-identifier",
  "timestamp": "2021-12-22T17:21:44.880-0600",
  "checksum": "checksum-of-sdk-captured-data",
  "version": 1
}

A few details about each value:

  • valid returns true when a human is detected and false for bots.
  • identifier returns the same value you provided to the SDK.
  • timestamp represents when the token was generated on the device. This value can be helpful in making sure tokens were recently generated.
  • checksum uniquely summarizes the data captured from the device. This value can be used on your backend to prevent replay attacks using the same token.
  • version is currently always 1.

Common behaviors when valid is false include denying access to your APIs from this user, throttling certain behaviors or functionality, or flagging the account for manual review.

For additional details, refer to the API reference.

If you have any questions, please reach out to us at support@unify.id.

Updated: