Skip to content

Keys API

The Keys API is a part of the Integrators API, and is used to get, create, and revoke keys on a specific 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 keys

GET integrators/v1/lock-holders/:lockHolderId/keys

Returns all keys to locks belonging to this lock holder.
Only returns keys made using the api, i.e. not keys made via the app.

Request

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

Example:
GET integrators/v1/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/keys

Response

200

The endpoint returns an array named "keys", with each key having the following fields:

Field Optional Type Location Description
id no string body UUID for this key
toUser no object body Object representing the user this key is for, fetched from our database. Contains phone number as id, and name and imageUrl if the user have added these.
lockId no string body Id of the lock this key belongs to
start no string body ISO8601-formatted date for when this key is active from.
end no string body ISO8601-formatted date for when this key expires. Is null for no expiry.
created no string body ISO8601-formatted date for when this key was first created
state no string body What state the key is currently in. See Key States for details.

Example:

{
   "keys": [
        {
            "id": "e678acba-c164-4ba5-bec1-839cf706b878",
            "toUser": {
                "id": "+4781549300",
                "name": "Bowler",
                "imageUrl": "www.example.com/image"
            },
            "lockId": "19398e97-cef8-4e3e-90a2-43162f319356",
            "start": "2020-01-15T14:08:47.000Z",
            "end": null,
            "created": "2020-01-15T14:08:47.000Z",
            "state": "active"
        },
        {
            "id": "3c4811d6-6a1e-40c0-981a-5ddcdbe85f45",
            "toUser": {
                "id": "+4781549300",
                "name": "Bowler",
                "imageUrl": "www.example.com/image"
            },
            "lockId": "19398e97-cef8-4e3e-90a2-43162f319356",
            "start": "2020-01-31T12:00:00.000Z",
            "end": "2020-02-14T12:00:00.000Z",
            "created": "2020-01-15T14:08:47.000Z",
            "state": "scheduled"
        }
    ]
}

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 keys for lock

GET integrators/v1/lock-holders/:lockHolderId/locks/:lockId/keys

Returns all keys to the given lock, except those that are expired, revoked or in error.
Only returns keys made using the api, i.e. not keys made via the app.

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 integrators/v1/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/locks/19398e97-cef8-4e3e-90a2-43162f319356/keys

Response

200

The endpoint returns an array named "keys", with each key having the following fields:

Field Optional Type Location Description
id no string body UUID for this key
toUser no object body Object representing the user this key is for, fetched from our database. Contains phone number as id, and name and imageUrl if the user have added these.
lockId no string body Id of the lock this key belongs to
start no string body ISO8601-formatted date for when this key is active from.
end no string body ISO8601-formatted date for when this key expires. Is null for no expiry.
created no string body ISO8601-formatted date for when this key was first created
state no string body What state the key is currently in. See Key States for details.

Example:

{
   "keys": [
        {
            "id": "e678acba-c164-4ba5-bec1-839cf706b878",
            "toUser": {
                "id": "+4781549300",
                "name": "Bowler",
                "imageUrl": "www.example.com/image"
            },
            "lockId": "19398e97-cef8-4e3e-90a2-43162f319356",
            "start": "2020-01-15T14:08:47.000Z",
            "end": null,
            "created": "2020-01-15T14:08:47.000Z",
            "state": "active"
        },
        {
            "id": "3c4811d6-6a1e-40c0-981a-5ddcdbe85f45",
            "toUser": {
                "id": "+4781549300",
                "name": "Bowler",
                "imageUrl": "www.example.com/image"
            },
            "lockId": "19398e97-cef8-4e3e-90a2-43162f319356",
            "start": "2020-01-31T12:00:00.000Z",
            "end": "2020-02-14T12:00:00.000Z",
            "created": "2020-01-15T14:08:47.000Z",
            "state": "scheduled"
        }
    ]
}

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": "notFound",
    "error_description": "Could not find lock with id \"73289bd1-6d3e-4dba-9e95-faf96899e480\""
}

Create new key

POST integrators/v1/lock-holders/:lockHolderId/locks/:lockId/keys

Create a new key to this lock for the specified user.
A user, identified by a phone number, may have any number of keys to a lock.
It is possible to create keys to users who have not yet logged in to the app.

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 body E.164-formatted phone number for the user this key is for
start no string body ISO8601-formatted date for when this key is active from. Null for immediately.
end no string body ISO8601-formatted date for when this key expires. Null for no expiry.
skipInviteNotification yes boolean body Whether or not to send a push notification to the user when creating this key. Defaults to false

Example:
POST integrators/v1/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/locks/19398e97-cef8-4e3e-90a2-43162f319356/keys

{
    "userId": "+4781549300",
    "start": "2020-01-31T12:00:00.000Z",
    "end": null,
    "skipInviteNotification": false
}

Response

200

Returns the created key

Field Optional Type Location Description
id no string body UUID for this key
toUser no object body Object representing the user this key is for, fetched from our database. Contains phone number as id, and name and imageUrl if the user have added these.
lockId no string body Id of the lock this key belongs to
start no string body ISO8601-formatted date for when this key is active from.
end no string body ISO8601-formatted date for when this key expires. Is null for no expiry.
created no string body ISO8601-formatted date for when this key was first created
state no string body What state the key is currently in. See Key States for details.

Example:

{
    "key": {
        "id": "3c4811d6-6a1e-40c0-981a-5ddcdbe85f45",
        "toUser": {
            "id": "+4781549300",
            "name": "Bowler",
            "imageUrl": "www.example.com/image"
        },
        "lockId": "19398e97-cef8-4e3e-90a2-43162f319356",
        "start": "2020-01-31T12:00:00.000Z",
        "end": null,
        "created": "2020-01-15T14:08:47.000Z",
        "state": "scheduled"
    }
}

4xx
Field Optional Type Location Description
error no string body The type of error that occurred
error_description no string or array body Verbose description of the error, possibly an array of validation errors.

Example:

{ 
    "error": "invalidRequest",
    "error_description": [
        ["userId", "must be present"]
    ]
}

Update a key

PUT integrators/v1/lock-holders/:lockHolderId/locks/:lockId/keys/:keyId

This is the only way to revoke a key.

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
keyId no string url Id of the key to update.
state no string body The state you wish to set the key in. Only "revoked" is supported for now.

Example:
PUT integrators/v1/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/locks/19398e97-cef8-4e3e-90a2-43162f319356/keys/3c4811d6-6a1e-40c0-981a-5ddcdbe85f45

{
    "state": "revoked"
}

Response

200

Returns the updated key

Field Optional Type Location Description
id no string body UUID for this key
toUser no object body Object representing the user this key is for, fetched from our database. Contains phone number as id, and name and imageUrl if the user have added these.
lockId no string body Id of the lock this key belongs to
start no string body ISO8601-formatted date for when this key is active from.
end no string body ISO8601-formatted date for when this key expires. Is null for no expiry.
created no string body ISO8601-formatted date for when this key was first created
state no string body What state the key is currently in. See Key States for details.

Example:

{
    "key": {
        "id": "3c4811d6-6a1e-40c0-981a-5ddcdbe85f45",
        "toUser": {
            "id": "+4781549300",
            "name": "Bowler",
            "imageUrl": "www.example.com/image"
        },
        "lockId": "19398e97-cef8-4e3e-90a2-43162f319356",
        "start": "2020-01-31T12:00:00.000Z",
        "end": null,
        "created": "2020-01-15T14:08:47.000Z",
        "state": "revoked"
    }
}

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": "notFound",
    "error_description": "Could not find lock with id \"73289bd1-6d3e-4dba-9e95-faf96899e480\""
}

Key States

State Description
creating The key has been entered into the system and we are in the process of creating it.
scheduled The key has been created and start is in the future. The key is not currently usable.
active The key is currently usable.
expired The key has end in the past. The key is not usable.
error There was an error when creating this key. If trying again does not work, check the lock holder's vendor connection. The key is not usable.
revoked The key has been manually revoked. The key is not usable.