Roles

Getting Roles from a Lock

You can review all the Roles associated with a Lock Holder by querying the Roles endpoint with a GET request:

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

Example:

curl --location --request GET '<<api_url>>/integrators/v1/lock-holders/27df4c8b-a71a-4e08-bd08-79fbbf79ddaf/roles/' \
--header 'Authorization: Bearer mV4cI6MTY1NDAzMjI3N3IiXX0m2hU91eGGWP.muTmF5eUiOiJSb2N0c0bkwVwnwcetb'

The response will have a JSON object with a Roles key referencing an array of Roles, like this:

{
    "roles": [
        {
            "userId": "+523377360535",
            "lockId": "a3d0a36b-c52f-4152-9e21-2158095051af",
            "canShare": true,
            "created": "2021-05-20T12:35:03.879Z",
            "createdKeys": 1
        },
        {
            "userId": "+523377360538",
            "lockId": "c78a7423-b067-4e8d-b630-9ee8829cde83",
            "canShare": true,
            "created": "2021-05-20T12:35:03.880Z",
            "createdKeys": 1
        }
    ]
}

Creating and updating a Role

The Role creation and updating process share the same API endpoint. To use it, you send a PUT request to:

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

In the request body you will include the name you want to use for this User on this Lock and whether this User will be able to share new Keys or not:

• userName: The user name to be displayed for this user on this lock
• canShare: A Boolean value specifying if this user can share new keys or not

Example:

curl --request PUT '<<api_url>>/integrators/v1/lock-holders/866b8a35-4184-44c5-8ffd-448a77e5a91c/locks/ba193242-3cb2-4ac7-beef-d41668a009bb/roles/4781549300' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer mV4cI6MTY1NDAzMjI3N3IiXX0m2hU91eGGWP.muTmF5eUiOiJSb2N0c0bkwVwnwcetb' \
--data-raw '{
	"userName": "Mr. Normann",
	"canShare": false
}'

The API will send back the new Role represented as a JSON object:

{
  "role": {
  "userId": 4781549300,
  "userName": "Mr. Normann",
  "lockId": "19398e97-cef8-4e3e-90a2-43162f319356",
  "canShare": false,
  "created": "2020-01-15T14:08:47.000Z",
  "createdKeys": 1,
}

You now know how to authenticate your requests based on the different Scopes the Integrator API provides, you also know the essentials of managing Lock Holders, Locks, Keys and Roles. You can continue taking this knowledge to the next level by:

• Reading our Guides to explore specific functionalities you can add to your app
• Exploring the Reference Implementation we provide to see how we put our API to work in a sample web app
• Read the API reference to get all the information about Unloc's APIs and use them to their full potential