Get keys for a lock

To get all the keys of a specific Lock you can make a GET request to:

https://api.unloc.app/integrators/v1/lock-holders/{{your_lock_holder_id}}/locks/{{your_lock_id}}/keys/

Here's an example:

curl --request GET '<<api_url>>/integrators/v1/lock-holders/866b8a35-4184-44c5-8ffd-448a77e5a91c/locks/ba193242-3cb2-4ac7-beef-d41668a009bb' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer mV4cI6MTY1NDAzMjI3N3IiXX0m2hU91eGGWP.muTmF5eUiOiJSb2N0c0bkwVwnwcetb' \

This will return a response with the following structure:

{
  "keys": [
    {
      "toUser": {
      "id": 61452912456,
      "imageUrl": "http://www.example.com/image.jpg"
    },
    "start": "2020-01-28T18:00:00.000Z",
    "end": "2020-01-29T18:00:00.000Z",
    "created": "2021-06-09T07:42:19.303Z",
    "state": "creating",
    "recurrence": {...},
    }
  ]
}

Notice the recurrence property, this is one of the key features of the Unloc platform; this will define the days of the week and the times when the Key is active. You can easily set this up when creating a new Key.

Read more about recurring keys on this guide .

Creating a Key

Creating a Key for a Lock is a straightforward and flexible process. You will use the same endpoint you use to get the Lock Keys, only this time you send a POST request:

https://api.unloc.app/integrators/v1/lock-holders/{{your_lock_holder_id}}/locks/{{your_lock_id}}/keys/

Inside the request body you should include at least the following properties:

  • userId: The mobile phone number of the user that will get this Key. You should use the E.164 format.
  • start: The date from which this key will start working. You should use the ISO-8601 format. If you want the key to start working immediately, you should send null.
  • end: The expiration date for this key, again you should use the ISO-8601 format. If you don't want to set an expiration date for this key, you should send null instead.

One of Unloc's platform key feature is the ability to create recurring keys to for instance only allow a certain Key to be used during weekdays from 9 to 18. Check out the recurring Keys guide for more.

Example:

curl --location --request POST '<<api_url>>/integrators/v1/lock-holders/27df4c8b-a71a-4e08-bd08-79fbbf79ddaf/locks/0634f1ba-e175-49e8-98bc-32b11505107b/keys/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer mV4cI6MTY1NDAzMjI3N3IiXX0m2hU91eGGWP.muTmF5eUiOiJSb2N0c0bkwVwnwcetb' \
--data-raw '{
	"userId": "+523377360555",
	"start": null,
	"end": null,
	"skipInviteNotification": true
}'

As you can see, there's an additional property called skipInviteNotification. This is an optional property you can use when you don't want the specified User to be notified of the Key creation either by SMS or a push notification if they have Unloc's mobile app installed. You can read more about Notifications here .

The API will respond to this request with a Key object, like this one:

{
    "key": {
        "id": "b99a1d1f-0a9a-4723-bd5b-4ff1614c7735",
        "toUser": {
            "id": "+523377360555"
        },
        "lockId": "0634f1ba-e175-49e8-98bc-32b11505107b",
        "start": "2021-06-24T11:59:14.926Z",
        "end": null,
        "created": "2021-06-06T06:05:59.926Z",
        "state": "creating"
    }
}

๐Ÿ“˜

Start time

Notice that since a start time wasn't set in the creation request, the start time was that same moment and so the response's start and created times are the same.


Whatโ€™s Next

Next up is the concept of Roles