Skip to content

Roles API

The Roles API is a part of the Integrators API, and is used to get, create, and update roles on a specific lock.
For now roles are only used to allow sharing keys.
A user may not have more than one role per lock.

Using this API requires having a JWT scoped for a Lock Holder. See Authentication for details.

If you don't have a Lock Holder yet you can create one using the Lock Holder API

Endpoints

Get all roles

Get all roles for this lock. Will only return roles able to share keys.

GET lock-holders/:lockHolderId/locks/:lockId/roles

Request

Field Optional Type Location Description
lockHolderId no string url Id of the lock holder. Must match the one in the JWT scope.
lockId no string url Id of the lock. Must be owned by the lock holder.

Example:
GET https://api.unloc.app/integrators/v1/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/locks/19398e97-cef8-4e3e-90a2-43162f319356/roles

Response

200

The endpoint returns an array named roles, with each role having the following fields:

Field Optional Type Location Description
userId no string body Id of the user who has this role. E.164-formatted phone number.
userName yes string body Display name for this user. Display name is unique per lock per user.
lockId no string body Id of the lock this role belongs to.
canShare no boolean body Whether or not this role allows the user to share keys to this lock.
created no string body ISO8601-formatted date for when this role was first created.

Example

{
    "roles": [
        {
            "userId": "+4781549300",
            "userName": "Bowler",
            "lockId": "19398e97-cef8-4e3e-90a2-43162f319356",
            "canShare": "true",
            "created": "2020-01-15T14:08:47.000Z"
        },
        {
            "userId": "+4781549200",
            "userName": "Top",
            "lockId": "19398e97-cef8-4e3e-90a2-43162f319356",
            "canShare": "true",
            "created": "2020-01-15T14:08:48.000Z"
        }
    ]
}

4xx
Field Optional Type Location Description
error no string body The type of error that occurred
error_description no string body Verbose description of the error

Example

{ 
    "error": "notFound",
    "error_description": "Could not find lock with id \"73289bd1-6d3e-4dba-9e95-faf96899e480\""
}

Create or update role

PUT lock-holders/:lockHolderId/locks/:lockId/roles/:userId

Allow or disallow a user to share keys to this lock.
We strongly recommend also creating a key for this user to this lock when first allowing a user to share keys.

Request

Field Optional Type Location Description
lockHolderId no string url Id of the lock holder. Must match the one in the JWT scope.
lockId no string url Id of the lock. Must be owned by the lock holder.
userId no string url Id of the user who has the role. E.164-formatted phone number.
canShare no boolean body Whether or not this role allows sharing keys for this lock.
userName yes string body Display name for this user on this lock.

Example:
PUT https://api.unloc.app/integrators/v1/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/locks/19398e97-cef8-4e3e-90a2-43162f319356/roles/+4781549300

{
    "canShare": true,
    "userName": "Bowler Hattson"
}

Response

200

Returns the updated role

Field Optional Type Location Description
userId no string body Id of the user who has this role.
userName yes string body Display name for this user. Display name is unique per lock per user.
lockId no string body Id of the lock this role belongs to.
canShare no boolean body Whether or not this role allows the user to share keys to this lock.
created no string body ISO8601-formatted date for when this role was first created.

Example:

{
    "role": {
        "userId": "+4781549300",
        "userName": "Bowler Hattson",
        "lockId": "19398e97-cef8-4e3e-90a2-43162f319356",
        "created": "2020-01-31T12:00:00+0000",
        "canShare": true
    }
}
4xx
Field Optional Type Location Description
error no string body The type of error that occurred
error_description no string body Verbose description of the error
{ 
    "error": "invalidRequest",
    "error_description": [
        ["canShare", "must be boolean"]
    ]