Skip to content

Locks

Get List of Locks

GET/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.

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
  }
]

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/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.

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
}

Expandable properties

Please see the expandable properties of the

GET/Owners/{ownerAccountId}/BoundLocks/

operation above.

Bind Lock

PUT/Owners/{ownerAccountId}/BoundLocks

Bind a new lock to the owner account.

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.

Scope

write:core:entities

Parameters

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

Body

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

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
}

In case the lock cannot be registered with a binding code, but has to be bound using functionality from the Tapkey Mobile SDK, the operation will return:

400 No active binding exists for this lock.

If the provided binding code is invalid, the operation will return:

400 Binding code not found.

If the lock is already bound to another owner account, this operation will return:

400 Another bound lock already exists.

Patch Lock

PATCH/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."
}

Response

204 No Content

Unbind Lock

DELETE/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.

Response

204 No Content

Or, in case the force parameter is set to false and related, active grants exist:

400 Active grants exist for this lock, revoke them first.

Replace Lock

POST/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"
}

Response

204 No Content

If the old lock is not found, the operation will return:

400 old bound lock not found

If the old bound lock equals the new one:

400 lock cannot be replaced by itself

In case the old lock has already been deleted:

400 old lock has already been unbound

In case the old lock has already been replaced:

400 lock has already been replaced

In case the new lock has active grants:

400 Active grants exist for the current substitute lock, revoke them first.

In case the new lock is member of a lock group:

400 The new lock is member of one or more lock groups - remove them first.

Or, in case the new lock is running an older firmware than the new one, the operation will return:

400 the replaced lock had a newer firmware installed; upgrade this locks firmware first

Get Grants for Lock

GET/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.

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": null,
      "ipUserId": null,
      "email": "user1@tapkey.com",
      "ipUserName": "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."
    }
  }
]

Get Group Memberships for Lock

GET/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.

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
  }
]

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/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.
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.
ActivateFirmware A new firmware was installed and activated.
ExecuteCustomCommand A custom, manufacturer-specific command was executed.
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.
State General state information was recorded.
StorageBlockCorrupted Storage corruption 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, undocumended 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

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.

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"
  }
]

Get Details of Lock

GET/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.

Response

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