Keys

Digital keys are time-limited and assigned to either a person (identified via their mobile phone number) or a partner. All key use is logged as events in the Unloc backend. All events older than 2 months are deleted for GDPR-compliance.

Creating keys

Creating a key is an asynchronous operation. The Unloc Partner API will return HTTP status 202 (Accepted) with the assigned ID of the newly minted key in the response body.

New keys are not guaranteed to be ready for use (in active state) the moment the response arrives. For many lock types, it might take a few seconds until the key has transitioned to the active state. See the Get key details API on how to query the key's state.

Create a new key

To create a new key for a given lock:

POST https://api.unloc.app/v1/partners/<Partner ID>/keys

The request body must contain the following fields:

Field Meaning
lockId The ID of the lock that the key should be created for
msn Mobile phone number of the recipient of the key, or null if the key is not assigned to a specific person. If msn is set to null, then the key can only be accessed via the Unloc Work app using App Switch.
start When the key should begin to be valid (ISO-8601 datetime)
end (optional)  When the key should stop being valid (ISO-8601 datetime). If omitted, the key does not expire.
route (optional) A key can be specified to belong to a named route. The Unloc Work app will download and cache all other keys for a given route whenever a key that belongs to a route is downloaded. The route value is opaque to Unloc. In other words, it need only make sense to the partner creating the key.
returnUrl (optional) If a return URL is specified, then the response body will include a field named appSwitchUrl. See The Unloc Work App for details on how to use this field.
curl -X POST \
-H "Authorization: Bearer rGUM658NwnnwrT4xZXVQGia3o2pQJwYe" \
-H 'Content-Type: application/json' \
-d '{
    "lockId":"danalock-d4:b5:8f:59:47:79",
    "start":"2018-06-01T20:30:00Z",
    "end":"2018-06-01T21:00:00Z",
    "msn":"+4790000000",
    "returnUrl": "https://unloc.app"
  }' https://api.unloc.app/v1/partners/abcpartner/keys

The JSON response includes the ID of the newly created key. In addition, if the returnUrl field has been specified, then the response will also include appSwitchUrl.

{
  "id" : "117ec32d-5ac3-422b-82de-cbb64540bffd",
  "appSwitchUrl": "ai.unloc.pro://use-key?id=86477029-5db2-4bc4-bdf9-eaf2e9aad759&r=myapp://&n=acbpartner&s=09ffe07e72343e1e456b2e64618f99fba4691e4c1323d0f98dba139d6bca83ba"
}

Batch create keys

Keys can be created in batch. To batch create a set of new keys:

POST https://api.unloc.app/v1/partners/<Partner ID>/batch/keys

The request body must be an array named keys. Each element in the array must contain the same values as for Create a new key.

curl -X POST \
-H "Authorization: Bearer rGUM658NwnnwrT4xZXVQGia3o2pQJwYe" \
-H 'Content-Type: application/json' \
-d '{"keys": [ 
      {
        "lockId": "3aa3856e-f1f4-477a-a564-f82290052f91",
        "start": "2018-06-01T20:30:00Z",
        "end": "2018-06-01T21:00:00Z",
        "msn": "+19175559001"
      },
      {
        "lockId": "a555703e-925f-4856-84f1-626e86df9294",
        "start": "2018-06-01T21:30:00Z",
        "end": "2018-06-01T22:30:00Z",
        "msn": "+19175559002",
        "returnUrl": "https://unloc.app"
      }
 ] }' \
https://api.unloc.app/v1/partners/abcpartner/batch/keys

The JSON response contains an array of objects corresponding to the keys request body supplemented with the following elements:

Field Meaning
id The ID of the newly created key (or null if the key did not pass validation)
appSwitchUrl The app switch URL, if a returnUrl was supplied in the keys request
status  OK if the key passed validation. ERROR if the validation failed.
error The validation error message, if status was ERROR
[
  {
    "id": "ffd699c0-9c27-4e8f-9e5c-c7549433d43c",
    "lockId": "3aa3856e-f1f4-477a-a564-f82290052f91",
    "start": "2018-06-01T20:30:00Z",
    "end": "2018-06-01T21:00:00Z",
    "msn": "+19175559001",
    "status": "OK"
  },
  {
    "id": "01af8f7e-a053-466a-b65a-8bcda889d137",
    "lockId": "a555703e-925f-4856-84f1-626e86df9294",
    "start": "2018-06-01T21:30:00Z",
    "end": "2018-06-01T22:30:00Z",
    "msn": "+19175559002",
    "returnUrl": "https://unloc.app",
    "appSwitchUrl": "ai.unloc.pro://use-key?id=2afec32d-5ac3-422b-82de-cbb64540beef&r=https://unloc.app&n=acbpartner&s=09ffe07e72343e1e456b2e64618f99fba4691e4c1323d0f98dba139d6bca83ba",
    "status": "OK"
  }
]

Note

Each batch can include up to 500 keys. To create more than 500 keys, you need to run several batches.

Get key details

Partners can request key details. Details include the current state of the key, and an array of key usage events. Note that key usage events are deleted after 60 days.

curl -H "Authorization: Bearer rGUM658NwnnwrT4xZXVQGia3o2pQJwYe" \
https://api.unloc.app/v1/partners/abcpartner/keys/117ec32d-5ac3-422b-82de-cbb64540bffd

The JSON response is the key with usage data (events).

{
    "id": "117ec32d-5ac3-422b-82de-cbb64540bffd",
    "lockId": "danalock-d4:b5:8f:59:47:79",
    "state": "revoked",
    "start": "2019-06-05T11:00:00.000Z",
    "end": "2019-06-10T17:00:00.000Z",
    "events": [
        {
            "id": "00000180-09ae-473d-ad7f-a46d6895beef",            
            "action": "locked",
            "created": "2019-06-05T11:36:49.235Z",
            "msn": "+19175559001",
            "name": "August Flatby"
        },
        {
            "id": "0000b180-09ae-473d-ad7f-a46d6895feed",
            "action": "unlocked",
            "created": "2019-06-05T12:37:47.024Z",
            "msn": "",
            "name": "Partner X"
        },
    ]
}

Keys can be in either of the following states.

State  Meaning
creating  The key is being created
scheduled The key will become active (at the start time)
active The key is currently active
expired  The key is not longer active (it expired at the end time)
error The key is in an error state
revoked The key has been revoked (by its creator or by the lock owner)

Get all keys

Partners can fetch IDs for all partner keys in a given state.

curl -H "Authorization: Bearer rGUM658NwnnwrT4xZXVQGia3o2pQJwYe" \
https://api.unloc.app/v1/partners/abcpartner/keys?state=active

JSON response:

{
    "ids": [
        "bc304503-02ca-4f6c-8bbb-89ec2cc4c415",
        "e5bcd95f-8be3-4657-bbd9-2ed0991579d8",        
    ]
}

Revoke a key

Keys can be revoked. Revoked keys become immediately unusable.

curl -X DELETE \
-H "Authorization: Bearer rGUM658NwnnwrT4xZXVQGia3o2pQJwYe" \
https://api.unloc.app/v1/partners/abcpartner/keys/117ec32d-5ac3-422b-82de-cbb64540bffd

JSON response:

{
  "response": "OK"
}

Note

Revoked keys are permantly revoked, and cannot be un-revoked. Revoked keys can be fetched like any other key with the Get all keys API.