For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

Device hash blocking

About device hash blocking​

You can use our device hash blocking feature to block a physical device from activating or recovering on the Encap server.

To do this, the device hash is blocklisted on the Encap server. This means that any activation or recovery attempt from that device is rejected, regardless of which end-user or registration is involved.

Comparison to device hash locking

This feature is distinct from the Device hash locking feature, which locks existing registrations.

Device hash blocking in comparison prevents new registrations from being created on the device at all.

Example use case​

A device is identified as compromised or fraudulent. By blocking its device hash, you prevent the device from being used to activate any new registrations or perform a recovery, even after deactivation of existing registrations.

What is a device hash?​

For the complete documentation index, see llms.txt

A device hash is a SHA-256 hash of the unique hardware ID of a physical device.

  • For Android, the hardware ID is derived from the Settings.Secure.ANDROID_ID value in the Android SDK.
  • For iOS, the hardware ID is generated by the SDK using Apple's CFUUIDCreate function and stored in the end-user's iCloud Keychain.
Want to learn more?

To learn more, see the device hash appendix for Android and iOS.

How blocklisting works​

When a device hash is blocklisted, the Encap server enforces the block at the following points:

When a blocklisted device is blocked by the Encap server, the server sends an event callback for the operation with a FAILED status. This enables your platform to react immediately.

What does this mean?

For example, your platform could react by notifying your fraud or operations team.

Scoping​

The applicationId query parameter controls the scope of a blocklist entry:

API integration​

We provide endpoints for blocklisting in the Encap REST API. With these endpoints, you can carry out operations such as:

  • Check if a device hash is blocklisted.
  • Add a device hash to the blocklist.
  • Remove a device hash from the blocklist.

Check if a device hash is blocklisted​

You can use this endpoint to check if a device hash is blocklisted.

  • If the device hash is blocklisted, the operation returns 200 OK.
  • If the device hash is not blocklisted, the operation returns 404 Not Found.
Note
  • The deviceHash path parameter must be URL-safe Base64 encoded.
  • The applicationId query parameter is optional.
Check if a device hash is blocklisted
GET /api/smart-device/v1/blocklist/{deviceHash}?applicationId={applicationId}

Example​

Example: Request
GET /api/smart-device/v1/blocklist/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=?applicationId=myApp

Add a device hash to the blocklist​

You can use this endpoint to add a device hash to the blocklist.

  • If successful, the operation returns 204 No Content.
  • If the applicationId is provided in the request and the device hash is already blocklisted for that application, the operation returns 409 Conflict.
  • If the applicationId is omitted from the request, then device hash is blocklisted across all applications in the organisation that have an existing registration for this device.
Note
  • The deviceHash path parameter must be URL-safe Base64 encoded.
  • The applicationId query parameter is optional.
Add a device hash to the blocklist
POST /api/smart-device/v1/blocklist/{deviceHash}?applicationId={applicationId}

Example​

Example: Request
POST /api/smart-device/v1/blocklist/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=?applicationId=myApp

Remove a device hash from the blocklist​

You can use this endpoint to remove a device hash from the blocklist.

  • If successful, the operation returns 204 No Content.
  • If the entry does not exist, the operation returns 404 Not Found.
Note
  • The deviceHash path parameter must be URL-safe Base64 encoded.
  • The applicationId query parameter is optional.
Remove a device hash from the blocklist
DELETE /api/smart-device/v1/blocklist/{deviceHash}?applicationId={applicationId}

Example​

Example: Request
DELETE /api/smart-device/v1/blocklist/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=?applicationId=myApp

Blocklist response object​

When you retrieve device details using the Get device endpoint shown in the example below, the response includes a blocklist object if the device's hash is blocklisted.

Note

The blocklist field is only present in the response when the device hash is blocklisted.

Example​

Example: Request
GET /api/smart-device/v1/devices/{deviceId}
Example: Response (blocklist object only)
{
  "blocklist": {
    "ref": "/smart-device/v1/blocklist/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=?applicationId=myApp",
    "device_hash": "wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=",
    "created_at": "2026-05-21T10:30:00.000Z"
  }
}
On this page