Skip to content

Locks

Get List of Locks

GET/api/v1/Owners/{ownerAccountId}/BoundLocks

Get a list of this owner account's locks.

Scope

read:core:entities

Parameters

Tip

The returned list can be filtered using OData query parameters.

Name Type Location Description
ownerAccountId string path The owner account's ID.
expand string path Optional. A comma-separated list of expandable properties.

Success Response

200 OK
[
  {
    "active": true,
    "bindDate": "2018-12-12T12:00:00.000Z",
    "description": "A description for this lock.",
    "healthStatuses": null,
    "id": "1",
    "lastSeenRclSerialNo": null,
    "lastSeenRclUpdateDate": null,
    "lockType": {
      "id": "TK.Td30",
      "manufacturerId": 1,
      "modelName": "Td30",
      "supportedTechnologies": [
        "nfc",
        "ble"
      ]
    },
    "lockTypeId": "TK.Td30",
    "membershipStatistics": null,
    "ownerAccountId": "1",
    "physicalLockId": "AAChsgq2",
    "rclDate": "2018-12-24T12:00:00.000Z",
    "rclSerialNo": 3,
    "supportedFeatures": null,
    "targetType": "Lock",
    "title": "Entrance Door",
    "unbindDate": null
  }
]

Error Responses

HTTP Status Code Error Code Description
400 Generic error
401 Unauthorized
403 Forbidden

Expandable properties

Supported features

When passing supportedFeatures to the expand query parameter, the response will contain the following additional property:

"supportedFeatures": {
  "timeRestrictionIcalSupport": "Supported"
}
Membership statistics

When passing membershipStatistics to the expand query parameter, the response will contain the following additional property:

"membershipStatistics": {
  "ByState": [
    {
      "State": "UnjoinPending",
      "Count": 1
    },
    {
      "State": "Unjoined",
      "Count": 3
    }
  ]
}
Lock health status

When passing healthStatuses to the expand query parameter, the response will contain the following additional property,

"healthStatuses": [
  {
    "id": "1",
    "physicalLockId": "AAChsgq2",
    "timestamp": "2019-12-12T12:00:00.000Z",
    "type": "BatteryWarningLevel",
    "value": 1.0,
    "valueStatus": "Ok"
  }‚Äč
]

The property type can be either BatteryVoltage, Temperature, or BatteryWarningLevel and valueStatus can be Ok, Outdated or Invalid.

Warning

Please note, that due to the nature of Tapkey locks as offline-first devices, there is no guarantee that the device will ever be able to report its status back to the Tapkey Trust Service. Therefore, health status indications should only be used to provide additional guidance to users, but must not be understood as a source of valid, up-to-date status information. The latter can only be achieved by synchronizing a lock directly via BLE or NFC.

Get Lock by ID

GET/api/v1/Owners/{ownerAccountId}/BoundLocks/{id}

Get the specified lock.

Scope

read:core:entities

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.
id string path The bound lock's ID.
expand string path Optional. A comma-separated list of expandable properties.

Success Response

200 OK
{
  "active": true,
  "bindDate": "2018-12-12T12:00:00.000Z",
  "description": "A description for this lock.",
  "healthStatuses": null,
  "id": "1",
  "lastSeenRclSerialNo": null,
  "lastSeenRclUpdateDate": null,
  "lockType": {
    "id": "TK.Td30",
    "manufacturerId": 1,
    "modelName": "Td30",
    "supportedTechnologies": [
      "nfc",
      "ble"
    ]
  },
  "lockTypeId": "TK.Td30",
  "membershipStatistics": null,
  "ownerAccountId": "1",
  "physicalLockId": "AAChsgq2",
  "rclDate": "2018-12-24T12:00:00.000Z",
  "rclSerialNo": 3,
  "supportedFeatures": null,
  "targetType": "Lock",
  "title": "Entrance Door",
  "unbindDate": null
}

Error Responses

HTTP Status Code Error Code Description
400 Generic error
401 Unauthorized
403 Forbidden
404 Not found

Expandable properties

Please see the expandable properties of the

GET/api/v1/Owners/{ownerAccountId}/BoundLocks/

operation above.

Bind Lock

PUT/api/v1/Owners/{ownerAccountId}/BoundLocks

Bind a new lock to the owner account.

Scope

write:core:entities

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.

Using a binding code

Locks that come with a binding code can be bound (registered) using this operation. If the lock is already bound to another owner account, this operation will fail. The lock's binding code must be submitted when registering a new lock.

Warning

If the lock was previously bound to another owner account, a synchronization of the lock may be required to ensure keys originating from the previous owner account are not being accepted any more. For more information on binding locks, visit the Mobile SDK's guide on binding locks.

Body

{
  "physicalLockId": "AAChsgq2",
  "bindingCode": "abc123",
  "title": "Entrance Door",
  "description": "A description for this lock."
}

Success Response

200 OK
{
  "active": true,
  "bindDate": "2018-12-12T12:00:00.000Z",
  "description": "A description for this lock.",
  "healthStatuses": null,
  "id": "1",
  "lastSeenRclSerialNo": null,
  "lastSeenRclUpdateDate": null,
  "lockType": {
    "id": "TK.Td30",
    "manufacturerId": 1,
    "modelName": "Td30",
    "supportedTechnologies": [
      "nfc",
      "ble"
    ]
  },
  "lockTypeId": "TK.Td30",
  "membershipStatistics": null,
  "ownerAccountId": "1",
  "physicalLockId": "AAChsgq2",
  "rclDate": "2018-12-24T12:00:00.000Z",
  "rclSerialNo": 3,
  "supportedFeatures": null,
  "targetType": "Lock",
  "title": "Entrance Door",
  "unbindDate": null
}

Error Responses

HTTP Status Code Error Code Description
400 Generic error
400 BindingNotFound No active binding exists for this lock
400 AlreadyBound Another bound lock already exists
400 GroupMembershipsExistFromFormerBinding Group memberships exist for this lock - sync to remove them and retry
401 Unauthorized
403 Forbidden
409 NothingToDo Lock already bound

Using the offline binding process

The offline binding process allows binding a lock without having a binding code and without using the online binding process, which requires an online connection between the lock and the Tapkey Trust Service at the time the binding process is performed.

See Start Offline Binding to learn more about the offline binding process and how to start the process.

Body

{
  "physicalLockId": "AAChsgq2",
  "offlineBinding": {
    "metadata": "abcedefgh1234",
    "responseBlob": "abcedefgh1234",
  },
  "title": "Entrance Door",
  "description": "A description for this lock."
}
Name Type Description
offlineBinding.metadata string The metadata which was obtainted when starting the binding process.
offlineBinding.responseBlob string The response blob in Base64 encoded format as obtained from the locking device being bound.

Success Response

200 OK
{
  "active": true,
  "bindDate": "2018-12-12T12:00:00.000Z",
  "description": "A description for this lock.",
  "healthStatuses": null,
  "id": "1",
  "lastSeenRclSerialNo": null,
  "lastSeenRclUpdateDate": null,
  "lockType": {
    "id": "TK.Td30",
    "manufacturerId": 1,
    "modelName": "Td30",
    "supportedTechnologies": [
      "nfc",
      "ble"
    ]
  },
  "lockTypeId": "TK.Td30",
  "membershipStatistics": null,
  "ownerAccountId": "1",
  "physicalLockId": "AAChsgq2",
  "rclDate": "2018-12-24T12:00:00.000Z",
  "rclSerialNo": 3,
  "supportedFeatures": null,
  "targetType": "Lock",
  "title": "Entrance Door",
  "unbindDate": null
}

Error Responses

HTTP Status Code Error Code Description
400 Generic error
400 LockStateChanged Input parameters or lock state changed (Metadata considered invalid, because the lock's state changed, or other input parameters are invalid)
400 Expired Binding blob expired (Provided metadata expired)
401 Unauthorized
403 Forbidden
404 Lock not found
404 Lock group membership not found for lock

Patch Lock

PATCH/api/v1/Owners/{ownerAccountId}/BoundLocks/{id}

Patch the specified lock.

The following properties can be patched:

  • title
  • description

Scope

write:core:entities

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.
id string path The bound lock's ID.

Body

{
  "title": "Office Door",
  "description": "A new description for this lock."
}

Success Response

204 No Content

Error Responses

HTTP Status Code Error Code Description
400 Generic error
401 Unauthorized
403 Forbidden
404 Lock not found

Unbind Lock

DELETE/api/v1/Owners/{ownerAccountId}/BoundLocks/{id}

Unbind the specified lock.

This operation can be used to unbind (remove) locks from the owner account. Locks that have been removed are not visible anymore, and all related data, such as grants or the access log is lost as well. The operation's force parameter can be used to revoke all related grants while removing the lock. After this operation has completed, the lock requires synchronization for the changes to take effect.

Warning

After a lock has been removed using this this operation, users with active grants will still be able to open the lock. Unless it has been synchronized, the lock won't know that is has been unbound from the owner account and therefore still remains in its previous state.

Scope

write:core:entities

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.
id string path The bound lock's ID.
force boolean query Optional. If true, this operation will revoke all grants related to this lock. If false, the operation will fail if grants exist. Defaults to false.

Success Response

204 No Content

Error Responses

HTTP Status Code Error Code Description
400 Generic error
400 ActiveGrantsExist Active grants exist for this lock, revoke them first (In case the force parameter is set to false and related, active grants exist)
400 ActiveGroupMembershipsExist Active group memberships exist for this lock, revoke them first
401 Unauthorized
403 Forbidden
404 LockNotFound Lock not found
404 Lock group membership not found
409 NothingToDo Lock not bound

Replace Lock

POST/api/v1/Owners/{ownerAccountId}/BoundLocks/$/Replace

Replace the specified lock.

This operation can be used to replace a lock with a another lock registered within the same owner account. Any grants issued for the old lock will be transferred to the new lock. It is recommended that the new lock should not have any grants assigned prior to the invocation of this operation. If it does, the new lock's grants will be merged with the old lock's grants. In this case, if the old lock contains grants for the same smartphone user/card as the new lock, those of the old lock's may not be transferred.

Warning

This operation is only fully supported on locking devices starting with protocol version 3.12 (0x3c). On older devices, only smartphone-based grants will be transferred, while card-based grants may require synchronization of affected transponders.

Info

The firmware of the new lock must be based on the same or a newer version of the Tapkey Lock SDK than the firmware of the old lock.

Warning

In certain situations, it may be necessary to synchronize card-based transponders.

Info

After a lock has been replaced, the new lock needs to be synchronized using the Tapkey Mobile SDK's syncLockOnlineAsync() function in order to be fully functional.

The replaced lock will disappear from the list of locks after this operation has completed, while the new one will have all grants of the old one assigned. The IDs of the affected locks do not change during this process, leaving the new lock with the same ID as before. However, name and description as well as grants from the old lock will be copied over and applied on the new lock.

Scope

write:core:entities

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.

Body

{
  "oldBoundLockId": "1",
  "newBoundLockId": "2"
}

Success Response

204 No Content

Error Responses

HTTP Status Code Error Code Description
400 Generic error
400 ProtocolVersionTooOld The lock's protocol version is too old
400 ActiveGrantsExist Active grants exist for the current substitute lock, revoke them first
400 FwUpgradeRequired The replaced lock had a newer firmware installed; upgrade this locks firmware first
400 LockHasAlreadyBeenReplaced Lock has already been replaced
400 ActiveLockGroupMembershipsExist The new lock is member of one or more lock groups - remove them first
400 TooManyGroups This lock is already member of too many groups and therefore cannot join another group
400 AmbigousLicenseFound Ambigous license found
400 NotLicensed No valid license found for locking device/owner account/this purpose
401 Unauthorized
403 Forbidden
404 Old lock has already been unbound
404 LockNotFound New/Old bound lock not found

Get Grants for Lock

GET/api/v1/Owners/{ownerAccountId}/BoundLocks/{id}/Grants

Get a queryable list of grants for the specified lock.

Scope

read:grants

Parameters

Tip

The returned list can be filtered using OData query parameters.

Name Type Location Description
ownerAccountId string path The owner account's ID.
id string path The bound lock's ID.

Success Response

200 OK
[
  {
    "owner": null,
    "id": "1",
    "boundLockId": "1",
    "contactId": "1",
    "validFrom": null,
    "validBefore": null,
    "timeRestrictionIcal": null,
    "state": "Ok",
    "active": true,
    "boundCardId": null,
    "customPayload": null,
    "contact": {
      "id": "1",
      "comment": "A new comment describing this contact.",
      "ownerId": "1",
      "ipId": "tapkey",
      "ipUserId": null,
      "identifier": "user1@tapkey.com",
      "isActive": true,
      "title": "User One"
    },
    "boundCard": null,
    "boundLock": {
      "targetType": "Lock",
      "id": "1",
      "physicalLockId": "AAChsgq2",
      "title": "Entrance Door",
      "description": "A description for this lock."
    }
  }
]

Error Responses

HTTP Status Code Error Code Description
400 Generic Error
401 Unauthorized
403 Forbidden
404 Lock not found

Get Group Memberships for Lock

GET/api/v1/Owners/{ownerAccountId}/BoundLocks/{id}/Memberships

Get a queryable list of group memberships of the specified lock.

Scope

read:grants

Parameters

Tip

The returned list can be filtered using OData query parameters.

Name Type Location Description
ownerAccountId string path The owner account's ID.
id string path The bound lock's ID.
expand string path Optional. A comma-separated list of expandable properties.

Success Response

200 OK
[
  {
    "boundLock": null,
    "lockGroup": null,
    "lastSeenRclSerialNo": null,
    "lastSeenRclUpdateDate": null,
    "id": "1",
    "lockGroupId": "1",
    "boundLockId": "1",
    "joinStartDate": "2020-03-03T15:53:03.587Z",
    "joinCompletedDate": "2020-03-03T15:53:13.657Z",
    "leaveStartDate": "2020-03-27T14:00:36.800Z",
    "leaveCompletedDate": null
  },
  {
    "boundLock": null,
    "lockGroup": null,
    "lastSeenRclSerialNo": null,
    "lastSeenRclUpdateDate": null,
    "id": "2",
    "lockGroupId": "2",
    "boundLockId": "1",
    "joinStartDate": "2020-03-03T15:28:43.187Z",
    "joinCompletedDate": "2020-03-03T15:38:23.940Z",
    "leaveStartDate": null,
    "leaveCompletedDate": null
  }
]

Error Responses

HTTP Status Code Error Code Description
400 Generic Error
401 Unauthorized
403 Forbidden
404 Lock not found

Expandable properties

Bound lock

When passing boundLock to the expand query parameter, the response will contain the following additional property:

"boundLock": {
  "active": true,
  "rclSerialNo": 13,
  "rclDate": null,
  "targetType": "Lock",
  "id": "1",
  "physicalLockId": "BADhB7Iu",
  "title": "Entrance Door",
  "description": "Description of Entrance Door."
}
Lock group

When passing lockGroup to the expand query parameter, the response will contain the following additional property,

"lockGroup": {
  "active": false,
  "rclSerialNo": 5,
  "rclDate": null,
  "targetType": "Group",
  "id": "1",
  "physicalLockId": "DAAl1T7twFAiUeZ56tI=",
  "title": "Office Building",
  "description": "Description of the lock group."
}

Get Log Entries for Lock

GET/api/v1/Owners/{ownerAccountId}/BoundLocks/{id}/LogEntries

Get a queryable list of log entries related to the given lock.

Scope

read:logs

There are two types of log entries, Command and Event. Commands indicate, that the lock executed a command that most likely has been triggered by a user, while Events indicate, that some other kind of event, like a restart, a periodic measurement, etc. has occurred.

Commands can be one of the following:

Command name Description
DeactivateAdminMode The owner mode has been deactivated.
Unbind The lock as been unregistered (unbound) from it's owner.
Rebind The lock has been registered (bound) to an owner.
SetTime The lock's date/time was set. This event usually indicates that the lock's time has been synchronized with the time from the Tapkey Trust Service.
ChangeAdminMode The lock mode was changed, e.g. the owner mode was activated or deactivated.
PrepareFileUpload A file upload for a firmware upgrade was initiated. Before the actual firmware upgrade process, the firmware package is uploaded from the phone to the lock. This event marks the beginning of this process.
ActivateFirmware A new firmware was installed and activated.
ExecuteCustomCommand A custom, manufacturer-specific command was executed. Lock manufacturers can define their own custom commands that are specific to a certain type of lock.
TriggerLock The lock was locked/unlocked.

Events can be one of the following:

Event type Description
Provisioning The lock was born.
Bind The lock was registered (bound) to a new owner.
Unbind The lock was unregistered (unbound) from it's previous owner, marking the end of a bound lock's lifetime. Since it is not possible to retrieve log entries for an unbound lock, this event may not arrive at the server before the lock was bound again.
State General state information was recorded. Some locks report basic data like the battery state from time to time. A state event marks the recording of such a state.
StorageBlockCorrupted A corrupted block in the lock's storage was detected and repaired.
LogPageCorrupted Corruption of log data has been detected. Log entries might have been lost.
DeviceStarted The device was restarted, e.g. due to a power cycle or a firmware upgrade.

Other, undocumented command and event types exist that should be ignored by the client.

In order to get all TriggerLock events for a lock, the following OData query can be used:

$filter=logType eq 'Command' and command eq 'TriggerLock'

Parameters

Tip

The returned list can be filtered using OData query parameters.

Warning

As of today, log entries are limited to 365 days in the past.

Warning

The returned list should always be limited using OData query parameters, e.g. $skip=10&$top=5.

Name Type Location Description
ownerAccountId string path The owner account's ID.
id string path The bound lock's ID.

Success Response

200 OK
[
  {
    "id": "AAChsgq2;jzyRczNAJN1=;635",
    "entryNo": 635,
    "lockTimestamp": "2018-12-29T14:00:00.000Z",
    "receivedAt": "2018-12-29T14:00:05.000Z",
    "logType": "Command",
    "command": "TriggerLock",
    "eventType": null,
    "boundCardId": null,
    "boundLockId": "1",
    "contactId": "1",
    "measurements": [],
    "grantId": "1"
  },
  {
    "id": "AAChsgq2;jzyRczNAJN1=;64",
    "entryNo": 64,
    "lockTimestamp": "2018-12-14T14:00:00.000Z",
    "receivedAt": "2018-12-14T14:00:05.000Z",
    "logType": "Command",
    "command": "TriggerLock",
    "eventType": null,
    "boundCardId": null,
    "boundLockId": "1",
    "contactId": "1",
    "measurements": [],
    "grantId": "1"
  }
]

Error Responses

HTTP Status Code Error Code Description
400 Generic Error
401 Unauthorized
403 Forbidden

Get Details of Lock

GET/api/v1/Owners/{ownerAccountId}/BoundLocks/{id}/LockType

Get details about the lock type of the given lock.

This operation can be used to get more information about the type of a certain bound lock, e.g. the model name, manufacturer or which technologies it supports (Bluetooth, NFC).

Scope

read:core:entities

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.
id string path The bound lock's ID.

Success Response

200 OK
{
  "id": "TK.Td30",
  "manufacturerId": 1,
  "modelName": "Td30",
  "supportedTechnologies": [
    "nfc",
    "ble"
  ]
}

Error Responses

HTTP Status Code Error Code Description
400 Generic Error
401 Unauthorized
403 Forbidden

Start Offline Binding

POST/api/v1/Owners/{ownerAccountId}/PhysicalLocks/{physicalLockId}/StartOfflineBinding

Starts an offline binding process. The offline binding process differs from the regular binding process in that it doesn't require an online connection between the Tapkey Trust Service and the locking device at the time of the binding. It differs from binding via binding codes in that it provides full binding semantics, rather than a 'soft-binding' experience as offered by binding codes.

Offline binding involves the following steps: * Obtain a binding blob and binding metadata for a specific lock via this endpoint. * Activate the affected lock's owner mode * Send the binding blob to the lock being bound and let it process the binding blob. * (Deactivate the owner mode) * Complete the process by passing the response blob obtained from the lock to the bind lock endpoint, together with the metadata obtained from this endpoint.

The following restrictions apply: * The firmware of the lock must implement TLCP protocol version 0x3A or newer. * The time between starting and completing the offline binding process must not exceed 24 h. * No other binding processes may be performed in the meantime. * The user performing completing the binding process must be the same as the one starting it.

Scope

bind:locks:offline

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.
physicalLockId string path The TLCP lock ID in Base64 encoded format.

Success Response

200 OK

{
  "metadata": "abcdefghij01",
  "requestBlob": "abcdefghij01"
}
| Name | Type | Description | | ---- |------|-------------| | metadata | string | The metadata to be passed back when completing the binding process. | | requestBlob | string | The request blob in Base64 encoded format. |

Error Responses

HTTP Status Code Error Code Description
400 Generic Error
400 FwUpgradeRequired Offline binding is not supported by this lock firmware version
401 Unauthorized
403 Forbidden
404 Lock not found

Get Push Packages

GET/api/v1/Owners/{ownerAccountId}/PhysicalLocks/{physicalLockId}/PushPackages

Allows querying TLCP records that have been queued for delivery to the given locking device. The records are intended to be interpreted only by the locking devices they target. The returned data may contain details like updates to the revocation lists, etc.

Distinction key

Packages may contain a so called distionctionKey. The distinction key may be used to identify whether a previously queried record has been superseded. If the client has previously received a message having the same distinction key as a newer message, it may safely discard the older message and replace it with the newer one. If no distinction key or null is provided, the message shall be delivered in any case, even if a newer message is received without having a distinction key.

Warning

In most cases the Tapky Mobile SDK takes care of delivering TLCP messages between Tapkey-enabled locking devices and the Tapkey Trust Service and in these cases it's usually not required and therefore discouraged to use this operation. Use of this operation usually only makes sense in integration scenarios with devices having some kind of online connectivity.

Info

The data returned in the record field represents a TLCP Record. Records are usually wrapped into TLCP Messages before being transmitted to a Tapkey locking device. A single TLCP record can be transformed into a TLCP message by prepending 0101 [HEX].

Scope

read:ttcp

Parameters

Name Type Location Description
ownerAccountId string path The owner account's ID.
physicalLockId string path The TLCP lock ID in Base64 encoded format.

Success Response

200 OK
{
  "id": "abcdefghij01",
  "lockId": "abcdefghij01",
  "distinctionKey": "rcl&12345",
  "record": "aabbccddeeff"
}
Name Type Description
id string The ID of this message. May be null.
lockId string The TLCP lock ID in Base64 encoded format.
distinctionKey string The distinction key for this type of message or null as outlined above.
record string The Base64 encoded record data.

Error Responses

HTTP Status Code Error Code Description
400 Generic Error
401 Unauthorized
403 Forbidden
404 Lock not found