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 locking

About device hash locking​

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 locking feature to get and lock all registrations tied to a particular device hash using a single operation.

Comparison to device hash blocking

This feature is distinct from the Device hash blocking feature, which prevents new registrations from being created on the device at all.

Device hash locking in comparison locks existing registrations.

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?​

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 locking works​

Platform behavior​

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

Scoping​

The applicationId query parameter controls the scope of the operation:

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.
  • Lock 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.
  • The applicationId query parameter is optional.
Get registrations by device hash
GET /api/smart-device/v1/devices/deviceHashes/{deviceHash}?applicationId={applicationId}

Example​

Example: Request
GET /api/smart-device/v1/devices/deviceHashes/wBHQ4HC3yLEUvEwnX5EBTBAbKkCia35WwO1dxqiFvYo=?applicationId=myApp
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"
    }
  ]
}

Lock registrations by device hash​

You can use the Lock 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.
  • The applicationId query parameter is optional.
Tip

If event callbacks are configured for DEVICE_LOCKED, then this operation sends one event callback for each locked registration by default.

To suppress these event callbacks for this operation, you can add suppressEventCallback=true to the request.

Lock registrations by device hash
POST /api/smart-device/v1/devices/deviceHashes/{deviceHash}/lock?applicationId={applicationId}

Example​

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