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.

Response

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

Lock Health Status

The healthStatuses property may contain an array of health status objects of the following type:

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

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

Response

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

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
{
  "lockType": {
    "id": "TK.Td30",
    "manufacturerId": 1,
    "modelName": "Td30",
    "supportedTechnologies": [
      "nfc",
      "ble"
    ]
  },
  "supportedFeatures": {
    "timeRestrictionIcalSupport": "Supported"
  },
  "healthStatuses": null,
  "id": "1",
  "physicalLockId": "AAChsgq2",
  "lockTypeId": "TK.Td30",
  "ownerAccountId": "1",
  "bindDate": "2018-12-12T12:00:00.000Z",
  "unbindDate": null,
  "title": "Entrance Door",
  "description": "A description for this lock.",
  "rclSerialNo": 1,
  "rclDate": "2018-12-12T12:00:00.000Z"
}

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.

Get Grants for Lock

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

Get a queryable list of grants applicable to the given 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
[
  {
    "contact": {
      "id": "1",
      "ownerId": "1",
      "comment": "A new comment describing this contact.",
      "email": "user1@tapkey.com",
      "title": "User One"
    },
    "boundCard": null,
    "boundLock": {
      "lockType": {
        "id": "TK.Td30",
        "manufacturerId": 1,
        "modelName": "Td30",
        "supportedTechnologies": [
          "nfc",
          "ble"
        ]
      },
      "supportedFeatures": {
        "timeRestrictionIcalSupport": "Supported"
      },
      "healthStatuses": null,
      "id": "1",
      "physicalLockId": "AAChsgq2",
      "lockTypeId": "TK.Td30",
      "ownerAccountId": "1",
      "bindDate": "2018-12-12T12:00:00.000Z",
      "unbindDate": null,
      "title": "Entrance Door",
      "description": "A description for this lock.",
      "rclSerialNo": 3,
      "rclDate": "2018-12-24T12:00:00.000Z"
    },
    "id": "1",
    "boundLockId": "1",
    "contactId": "1",
    "validFrom": null,
    "validBefore": null,
    "timeRestrictionIcal": null,
    "state": "Ok",
    "active": true,
    "boundCardId": null
  }
]

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