Skip to content

Determining Locks available for unlocking

This section outlines how to determine, which locks should be presented to the user as candidates for triggering a lock/unlock action.

The whole authorization flow usually consists of the following steps:

  1. An administrator uses some system, e.g. the Tapkey App or some 3rd party co-working management platform to create an access permission. This access permission is sent to the cloud-based Tapkey Trust Service via the Tapkey Web API and stored there in the form of a Grant. A grant therefore represents the users permission to operate a certain lock (or group) and the related details like a recurring access schedule, etc.

As a grant is just a concept for storing a permission on server side, locking devices don't know anything about the concept of a grant. In order to unlock a locking device, what is needed by the lock is a Mobile Key.

  1. When a user logs in to a Tapkey-enabled mobile app and also at certain time intervals, the mobile app queries Mobile Keys for locking devices the user has been granted access to. Mobile Keys are issued by the Tapkey Trust Service based on a user's Grants and are usually limited in their lifetime. Even if the related Grant has an indeterminate validity, Mobile Keys issued for it will usually only have a lifetime of seven days and will be renewed automatically after four days (concrete values are subject to change). The Tapkey Trust Service creates Mobile Keys based on a user's Grants and sends them to the mobile app. The mobile app stores them in its local storage for further use.

  2. When a mobile app tries to unlock a locking device, it invokes functions provided with the Tapkey Mobile SDK and specifies the ID of the lock to connect to. The Tapkey Mobile SDK looks the related key up in its local storage and uses it for opening the lock. If no locally stored key is present in the local storage, a new key is queried from the Tapkey Trust Service just in time, so the user usually wouldn't notice whether a key has already been present or has been queried as part of the unlocking process.

For a mobile app to find out, which locks are candidates for being unlocked by the user, it could use several sources of information:

  1. The Mobile Keys stored locally in the phone's local storage. This list can be queried using the KeyManager.getLocalKeys() function. However, as querying of mobile keys after login is an asynchronous process and can take some time, especially if the number of keys to fetch is high, and because grant details could have changed since the last synchronization, this list can be incomplete or inaccurate.
  2. The list of Grants assigned to the given user, as stored on the Tapkey Trust Service and accessible via the UserGrantManager.fetchUserGrantsAsync() method. This list is complete and accurate but could be inaccessible if no online connectivity is available.
  3. If a 3rd party system like a co-working management platform is used for managing access, then this system could deliver a list of accessible locks as well.

As locally stored Mobile Keys can be incomplete or out of sync, and the online list of Grants isn't always available, it is recommended to combine those two when determining the list of locks to be offered to the user for unlocking.