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.

A role represents a user's rights on a lock, e.g. sharing keys to the lock. 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 locks belonging to this lock holder. Will only return roles able to share keys.

GET lock-holders/:lockHolderId/roles

Request

Field Optional Type Location Description
lockHolderId no string url Id of the lock holder. Must match the one in the JWT scope.
limit yes number query The number of records to return
startAfterId yes string query Used to get the next set of records. Included in the response if limit was set in the request

Example:
GET https://api.unloc.app/integrators/v1/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/roles?limit=2&startAfterId=+4781549400.19398e97-cef8-4e3e-90a2-43162f319356

Response

200

The endpoint returns an array named roles, with each entry 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.
createdKeys no number body Number of keys this role has shared via the app

If limit was set in the query the response body also contains a field called startAfterId. Set the startAfterId query param for the next request to the id just returned to get the next page of records.

Example

{
    "startAfterId": "+4781549200.19398e97-cef8-4e3e-90a2-43162f319356",
    "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": "validationFailed",
    "error_description": "Authorization header invalid or missing"
}

Get all roles for lock

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

Update the given user's rights on this lock.
When you give a user rights on a lock we strongly recommend also creating a key for the user to that lock.

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"]
    ]