Test Agent

The test agent offers a REST-style API for many of the functionalities that can be executed against a Tapkey locking device. It can be used for different kinds of tasks during development, testing and production, e.g. for automating certain functionalities or executing functions, that are not available via the regular Tapkey app.

Overview

The test agent is a mobile application that runs on an Android device and offers a web interface around its REST API which can be accessed from any device on the same network. The web interface provides a way to execute commands on Tapkey locks using the Android device's Bluetooth connection. While the web interface is convenient to use and sufficient for many use cases, the REST API can be used directly to automate different scenarios. The test agent comes with a set of ready-to-use scripts.

Caution

The connection to the test agent's web interface is not secure. Do not use the test agent in sensitive scenarios and take proper measures to secure your network.

Installation

The test agent is available upon request and delivered directly by Tapkey as a standalone application package. For installation, the *.apk must be transferred to and installed on an Android device. Once the application is installed, start the test agent using the start button in the app's main view. It will also show the address where the web interface is served. The web interface can now be accessed from any device on the same network and provides a convenient way to execute commands on Tapkey locks.

A screenshot of the test agent's main view

Info

In order to use the web interface, the device running the user-agent needs to be able to access internet resources.

Authentication

In order to allow the test agent to retrieve mobile keys or download firmware from the Tapkey Trust Service, the test agent must be authenticated first.

The following steps outline the authentication process for the test agent:

  1. Open the web interface from another device.
  2. Scroll to the authentication section (auth), which is the first section in the list of operations.
  3. Use the /login operation to authenticate using OAuth. Note that, due to the nature of the OAuth Authorization Code flow, this operation cannot be executed from the web interface directly, but instead must be accessed directly in a separate tab or window of the user agent.
  4. Once redirected to the Tapkey login page, log in to the desired Tapkey account and grant all requested permissions to the test agent.
  5. At this point, the user agent is redirected to localhost:8080, which is not accessible. Replace localhost with the address of the device running the test agent. Make sure to leave the rest of the URL untouched.1
  6. The test agent is now authenticated and ready to use.

Warning

The test agent will have access to all mobile keys and data that the user, who authenticated the agent, has access to.

Info

In order to use the OAuth flow as outlined in this section, the device running the user-agent needs to be able to access the Internet.

Sending Commands to the Lock

A laptop showing the test agent's web interface with the list of operations.

Scanning for Nearby Locks

In order to retrieve a list of nearby locks, use

POST/ble/startScan

followed by the

GET/ble/nearby

operation. This will yield a list of scan results:

{
  "C4:C5:C6:C7:4B:52": {
    "bluetoothAddress": "C4:C5:C6:C7:4B:52",
    "incompleteLockId": "AND0KcI=",
    "isLockIdComplete": false,
    "lastVisibility": 1568798497426,
    "rssi": -87
  },
  "00:11:22:33:CE:61": {
    "bluetoothAddress": "00:11:22:33:CE:61",
    "incompleteLockId": "ANC6Bbw=",
    "isLockIdComplete": false,
    "lastVisibility": 1568798508590,
    "rssi": -67
  },
  
}

Tip

For more information on lock IDs in Tapkey, consult the Mobile SDK's concept guide on Tapkey lock IDs.

Triggering Locks

Use the

POST/ble/lock/{lockId}/triggerLock

operation to trigger a lock. Note that the user who authenticated the test agent must hold a valid key for the lock for this command (and others) to succeed.

Info

Consult the parameter description in the test agent's web interface for more information about the required format of the {lockId} path parameter.

The operation will return with the lock's response, the command result:

{
  "batteryWarnLevel": 0,
  "commandResultCode": "Unauthorized",
  "isAdminMode": false,
  "isBound": true,
  "lockTime": "2019-09-18T11:26:53.000+02:00",
  "serverTime": {
    "bestTime": "2019-09-18T11:26:57.167+02:00",
    "localTime": "2019-09-18T11:26:57.478+02:00",
    "serverTime": "2019-09-18T11:26:57.167+02:00"
  },
  "userCommandResults": [
    {
      "userCommandResultCode": "Unauthorized",
      "userId": "3045f962-c6fc-487a-bee4-371a9b847ee4"
    }
  ]
}

Upgrading Firmware

The

POST/ble/lock/{lockId}/firmware/upgrade

operation can be used to upgrade a lock's firmware. The firmware package can either be retrieved from the Tapkey Trust Service using the

GET/ble/lock/{lockId}/firmware/package/{firmwareInfoId}

operation, or produced locally and passed to the upgrade-operation's post body.

Info

Consult the parameter description in the test agent's web interface for more information about the operations' parameters.


  1. There are a few alternatives to this cumbersome step, e.g. setting up a redirect with adb. This is outlined in the web interface's introductory text, section Authentication.