Vendor Connections API

The Vendor Connections API is a part of the Integrators API, and is used to create and update vendor connections.
A vendor connection represents a link between a lockHolder and a lock vendor, e.g. Danalock. Vendor connections are used to perform operations on your behalf, such as fetching your locks and making keys.

Using this endpoint requires having a JWT scoped for the 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

Create new vendor connection

POST integrators/v1/lock-holders/:lockHolderId/vendor-connections

Set up a new vendor connection from a vendor account. Username and password must match the ones you used to create the account with the vendor.
Call will fail if there is already a vendor connection with this username that does not have state error or disconnected.

Request

Field Optional Type Location Description
lockHolderId no string url Id of the lock holder. Must match the one in the JWT scope.
vendor no string body What lock vendor the account is registered with. Se table below for details.
username no string body Username for the account
password no string body Password for the account

Example: POST integrators/v1/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/vendor-connections

{
    "vendor": "danalock",
    "username": "testaccount@unloc.app",
    "password": "password123"
}

Response

200

Vendor connection was created successfully.

Field Optional Type Location Description
id no string body UUID for this vendor connection
state no string body Current state for this vendor connection, will be "connecting" when first created. See table below for details.
vendor no string body Same vendor as was passed in

Example:

{
    "vendorConnection": {
        "id": "8e217374-d1ff-43b1-9a99-540ea5645b30",
        "state": "connecting",
        "vendor": "danalock"
    }
}

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",
    "errorDescription": "The user credentials were incorrect."
}

Get all vendor connections

Get a list of all vendor connections associated to this lock holder, regardless of state.

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/vendor-connections

Response

Response is an array named vendorConnections where each entry has the following fields:

Field Optional Type Location Description
id no string body UUID for this vendor connection
state no string body Current state for this vendor connection. See table below for details.
vendor no string body What vendor this vendor connection is to

Example:

{
    "vendorConnections": [
        {
            "id": "3b162323-3295-4263-8cf9-071adfafc62a",
            "state": "error",
            "vendor": "danalock"
        },
        {
            "id": "d0f115a7-14ac-43a7-94ca-7e0740afc4e5",
            "state": "disconnected",
            "vendor": "danalock"
        },
        {
            "id": "e8ddb1be-9c8f-4244-ac1c-bfaa54a52f50",
            "state": "connected",
            "vendor": "danalock"
        }
    ]
}

Refresh vendor connection

PUT integrators/v1/lock-holders/:lockHolderId/vendor-connections/:vendorConnectionId/refresh

Refresh the vendor connection and all locks associated with it.
Use this call when you have added or removed locks from the vendor account.

Request

Field Optional Type Location Description
lockHolderId no string url Id of the lock holder. Must match the one in the JWT scope.
vendorConnectionId no string url Id of the vendor connection you wish to refresh.

Example PUT integrators/v1/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/vendor-connections/e8ddb1be-9c8f-4244-ac1c-bfaa54a52f50/refresh

Response

204

Refresh was completed successfully

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

Example:

{ 
    "error": "invalidRequest",
    "errorDescription": "The user credentials were incorrect."
}

Update vendor password

PUT integrators/v1/lock-holders/:lockHolderId/vendor-connections/:vendorConnectionId/update-password

Change the password to your vendor account. This endpoint will do an external call to the vendor to change the password there.
The vendor connection must be in the connected state.

Request

Field Optional Type Location Description
lockHolderId no string url Id of the lock holder. Must match the one in the JWT scope.
vendorConnectionId no string url Id of the vendor connection linked to the vendor account
password no string body The new password for the account. Might have length requirements depending on the vendor

Example PUT integrators/v1/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/vendor-connections/e8ddb1be-9c8f-4244-ac1c-bfaa54a52f50/update-password

{
    "password": "longsecurepassword"
}

Response

204

Password was updated successfully

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

Example:

{
    "error": "validationFailed",
    "errorDescription": [
        [
            "request", "should have required property 'password'"
        ]
    ]
}

Connection States

State Description
connecting Vendor connection has been created and our system is currently setting up required data. This should not take more than a few seconds, depending on the number of locks.
connected Vendor connection is fully established.
refreshing The system is currently in the process of refreshing the locks of this vendor connection.
disconnected This vendor connection is no longer active.
error There is something wrong with this vendor connection. There may be multiple causes, but the most probable fix is creating a new vendor connection with the same lock holder and credentials.