Skip to main content

Device hash blocking

About device hash blocking​

One physical device can be tied to several registrations. For example, this could happen after an end-user has re-registered using the same device.

You can use our device hash blocking feature to get and block all registrations tied to a particular device hash using a single operation.

Example use case​

An end-user reports their device as stolen. Using the device hash, you can immediately lock all active registrations associated with that physical device, without needing to track down each individual device ID.

What is a device hash?​

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.

Platform behavior​

Depending on the mobile platform, the device hash behaves differently when an app is reinstalled on the same device:

API integration​

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

  • Get all registrations tied to a physical device using its device hash.
  • Block all registrations tied to a physical device using its device hash.

Device hash response object​

Both device hash management endpoints return a device hash response object. For an overview of all response object fields, see the table below:

Example: Device hash response object
{
  "devices": [
    {
      "device_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "lock_status": "OPEN",
      "device_status": "ACTIVATED"
    }
  ]
}

Lock statuses​

For an overview of all lock statuses, see the table below:

Device statuses​

For an overview of all device statuses, see the table below:

Get registrations by device hash​

You can use the Get registrations by device hash endpoint to retrieve all registrations associated with a physical device, identified by its device hash.

Note
  • This operation retrieves both active and deactivated registrations within your organisation.
  • The deviceHash path parameter must be URL-safe Base64 encoded.
Get registrations by device hash
GET /api/smart-device/v1/devices/deviceHashes/{deviceHash}

Example​

Example: Request
GET /api/smart-device/v1/devices/deviceHashes/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=
Example: Response
{
  "devices": [
    {
      "device_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "lock_status": "OPEN",
      "device_status": "ACTIVATED"
    },
    {
      "device_id": "1cb72f91-3344-4812-a1de-7d845e22bcf1",
      "lock_status": "OPEN",
      "device_status": "DEACTIVATED"
    }
  ]
}

Block registrations by device hash​

You can use the Block registrations by device hash endpoint to lock all active and unlocked registrations associated with a physical device, identified by its device hash.

Note
  • This operation does not include registrations that have already been locked or deactivated.
  • The deviceHash path parameter must be URL-safe Base64 encoded.
Block registrations by device hash
POST /api/smart-device/v1/devices/deviceHashes/{deviceHash}/lock

Example​

Example: Request
POST /api/smart-device/v1/devices/deviceHashes/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=/lock
Example: Response
{
  "devices": [
    {
      "device_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "lock_status": "LOCKED_BY_ADMIN",
      "device_status": "ACTIVATED"
    }
  ]
}
On this page