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.
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.
The TLCP lock ID has the following format (each character here represents one byte):
LL: The length of the actual ID (
XXXX), encoded in 2 bytes, little endian.
XXXX: The actual ID.
The following ID of six bytes length has two bytes length header and four bytes ID payload:
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.
- 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/7for 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.,
AwD_AAY. (see RFC 4648 section 5; i.e.
/are replaced by
- As byte array: Throughout the TLCP protocol (when using the Tapkey Lock SDK), IDs are simply handled as byte arrays.