Skip to content

Lock IDs

When working with Tapkey, developers will encounter two different IDs related to Tapkey-enabled locking devices.

TLCP lock ID

The most relevant ID. Identifies a locking device uniquely within the Tapkey universe.

Bound lock ID
The bound lock ID identifies a certain locking device that is bound to (was registered by) a certain owner account. Note that one and the same lock may correspond to multiple bound locks over time, as it gets unregistered and registered again by multiple owners.

TLCP lock ID

The Tapkey Lock Control Protocol (TLCP) identifies locking devices by their TLCP lock ID. The lock ID can vary in length.

Info

Throughout the Tapkey Mobile SDK, the only lock ID relevant to developers is the TLCP lock ID, which is referred to as physicalLockId in parameters or return values. This is to emphasize the difference to the bound lock's ID. In all cases, the TLCP lock ID is expected and returned as a Base64-encoded string.

Structure

The TLCP lock ID has the following format (each character here represents one byte):

LLXXXX
  • LL: The length of the actual ID (XXXX), encoded in 2 bytes, little endian.
  • XXXX: The actual ID.

Example

The following ID of six bytes length has two bytes length header and four bytes ID payload:

04001234BFFB

The TLCP lock ID is represented in various formats throughout the Tapkey ecosystem:

  • Pretty formatted: To the customer, the ID is always presented as HEX, formatted without length header and bytes separated with dashes, e.g. 12-34-BF-FB.
  • Base 64 encoded: Within the Tapkey Management API and the Tapkey Mobile SDKs, IDs are encoded as regular Base64 strings when contained in JSON entities (e.g. BAASNL/7 for the ID above).
  • Base 64 encoded in URLs: Within the Tapkey Management API, IDs are encoded as URL-safe Base64 strings when contained in request URLs. E.g., BwC+AKzc/wEH becomes BwC-AKzc_wEH, and AwD/AAY= becomes AwD_AAY. (see RFC 4648 section 5; i.e. + and / are replaced by - and _ and trailing = are omitted).
  • As byte array: Throughout the TLCP protocol (when using the Tapkey Lock SDK), IDs are simply handled as byte arrays.

Incomplete lock IDs

When scanning for nearby locks via BLE, locks are represented through the concept of 'incomplete lock IDs'. The reason for this is that the Bluetooth protocol has certain restrictions on the length of an advertising ID, which might not fit the whole TLCP lock ID. The beginning of the ID may be trimmed to fit into the Bluetooth protocol.

Comparing TLCP lock IDs and incomplete lock IDs

In order to compare TLCP lock IDs (for example the physicalLockId found in the BoundLock model) and incomplete lock IDs (found in the BleLock model) you need to do it in a specific way.

First, both IDs should be in HEX-format. You might need to convert an ID to Base64 first, in order to convert it to HEX-format afterwards. Then check if the incomplete lock ID fully fits into the complete TLCP lock ID.

04001234BFFB <- TLC lock ID
  001234BFFB <- incomplete lock ID