Managing keys

The Unloc API provides a seamless way to manage Keys for your users. These Keys can be used in the Unloc App to open locks. This guide offers a walkthrough of how you can use the Unloc API to manage these Keys for your Project.

Creating keys

To create a Key, you'll need two primary pieces of information:

1. Recipient Identification: Who is the key for? We identify recipients through their mobile phone numbers. Ensure you provide an E.164 formatted number for the appUserId parameter.
2. Lock Identification: Which lock is the Key for? You'll need to find the lockId of one of the Locks belonging to your Project. You can use the Get Locks endpoint to view the available Locks in your Project.

That's it! Using the Create Keys endpoint with this input is enough to create a key. Here is an example:

curl --request POST \
     --url https://api.unloc.app/v2/projects/projectId/keys \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "keys": [
    {
      "lockId": "d6d8812e-48a9-11ee-b8a1-db05e53ca3e5",
      "appUserId": "+4799887766"
    }
  ]
}
'

However, there are multiple other parameters you can use to configure your Keys. Among these, the time-based parameters are very useful:

• start - Define when the key becomes functional using this parameter. It's perfect for scheduling access, say granting entry one week from today. We require the ISO 8601 date standard for formatting. For instance: 2024-01-01T08:00:00.000Z.
• end - Determine when the key expires. This lets you create temporary Keys for your users. Just like with the start parameter, the expected format is an ISO 8601 date.
• recurrence - Craft recurring keys with specified schedules. For instance, if you wish to permit access only on weekdays between 9:00 AM and 5:00 PM. For more details, refer to the Create Keys endpoint documentation.

There are more parameters you can use, but they are less important and you should look at the endpoint documentation for more details.

Processing Create Keys requests

Upon receiving a request to create Keys, depending on the vendor of the lock, we might have to contact the vendor lock system. Therefore the Create Keys request is asynchronous in nature and when you send the request you will get a reference to a Job as a response.

A Job represents the asynchronous process that handles the Key creation. With the provided Job reference you can track the Job's status and get a status on the progress. Status information comprises a resultData parameter which contains updates on which keys are:

• Being created
• Have been created successfully
• Have failed to be created

You can also see these Keys and their state by using the Get Keys endpoint. Keys that are being created will have the creating state. Keys that have been created successfully will have one of scheduled, active or inactive states. Finally, keys that have failed to have been created will have the error state.

Keys end up in the error state typically if we are unable to contact the underlying vendor lock system. This is often a temporary situation, but require manual intervention by the system's administrator.

Revoking Keys

Effective Key management also encompasses timely revocation. The Unloc API allows you to revoke any active Key at any time. Use the Revoke Key endpoint to revoke a specific Key, which subsequently alters its state to revoked. The Unloc App will register the state change and will not show or allow the key to be used anymore.

You can also revoke multiple keys at once, for example all Keys for a specific User, or all Keys for a specific Lock. Take a closer look at the Revoke Keys endpoint for more details.

Key expiration

Key expiration is the natural process of a Key reaching their end date. Unloc monitors all Keys and their end date, and transitions Keys state to expired when the end date is reached.

Keys without end date will never expire and will have to be revoked explicitly if needed.