Locks

A Lock is anything that can be locked/unlocked with a digital key.

Authorization

Lock owners can selectively grant partners the right to issue digital keys for their locks. By default, all partners are denied the right to issue digital keys to all locks, so no locks will be returned in the API response.

The following table shows the different values returned in the auth field, based on the given grant type:

Auth value Meaning
opt-in The lock owner must explicitly approve the partner's request to create a new key. The lock owner will receive a push notification asking the user to approve the request (whereby the user opts in to create the key)
opt-out The key created by the partner will automatically be approved by the user. Note that the user may retroactively decide to revoke the key (to opt-out from the key).

Info

If a lock is marked as opt-in, then you need to be aware that the key cannot be used unless the lock owner has accepted the key in the Unloc app.

Partner-specific data

The data field contains data that is only visible to you as a partner. For example, it can be useful to associate a customer ID or similar to the lock so that you can recognize your customers' locks.

Please contact Unloc directly for advice on how to associate partner-specific data with locks.

Get all locks

To get a list of all locks that you as a partner can create keys for:

GET https://api.unloc.app/v1/partners/<Partner ID>/locks

curl https://api.unloc.app/v1/partners/abcpartner/locks \
-H "Authorization: Bearer rGUM658NwnnwrT4xZXVQGia3o2pQJwYe"

The JSON response object contains an array of lock data:

{
    "locks": [
        {
            "auth": "opt-out",
            "data": "customer-001",
            "id": "danalock-00:00:00:00:00:01",
            "name": "Hjemme",
            "street": "Parkveien 4",
            "postalCode": "0351",
            "city": "Oslo",
            "countryIso": "no"
        },
        {
            "auth": "opt-out",
            "data": "customer-001",
            "id": "doora-00:00:00:00:00:01",
            "name": "Hovedinngang"
        }
    ]
}

The response lock data contains the following fields:

Field  Optional Meaning
id No The ID of the lock
name No The owner-assigned name of the lock
auth No Either opt-in or opt-out (see Authorization below)
data No Partner-specific (your) data associated with this lock
street Yes Street address of the lock
postalCode Yes Postal code
city Yes City
countryIso Yes Country ISO code

Get all key events

To get a list of all events for all partner-created keys on a lock:

GET https://api.unloc.app/v1/partners/<Partner ID>/locks/<Lock ID>/events

curl https://api.unloc.app/v1/partners/abcpartner/locks/BA193202-3CB2-4AC7-8045-D41668A009BB/events \
-H "Authorization: Bearer rGUM658NwnnwrT4xZXVQGia3o2pQJwYe"

The JSON response object contains an array of key events:

{
    "events": [
        {
            "id": "0001b180-09ae-473d-ad7f-a46d6895feed",
            "keyId": "f7d5f434-e8be-4a5b-ab2f-243d68fe7e88",
            "action": "unlocked",
            "name": "Franz Ferdinand",
            "msn": "+19175559999",
            "created": "2019-08-07T13:14:47.350Z"
        }
    ]
}