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 Web APIs 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 Web APIs, IDs are encoded as URL-safe Base64 strings without padding 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.