NAV Navbar
shell

Introduction

Welcome to the Doordeck API! You can use our API to access Doordeck API endpoints, which can get information on the state of locks, manage access and perform operations.

This API documentation is generated using Slate, if you spot any errors please submit a pull request directly on Github.

This API documentation includes details of both endpoints available to Doordeck users (i.e. users who have registered on Doordeck directly) and to third-party app developers, some endpoints are only available to one set of users, these are flagged as follows:

Environments

Doordeck operates production, staging and development environments at the following locations:

Newer endpoints may only exist in staging or development environments, these will be flagged as such.

Authentication

Doordeck uses tokens to permit access to the API. Doordeck expects for the token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer TOKEN

Authentication tokens are JSON Web Tokens (JWT) loosely using the OpenID format, they can be examined to determine their expiry date, the user's ID. JSON web tokens are split into three sections separated by a ., the header, payload and signature - each section can be BASE64URL decoded to read further.

Doordeck understands the following OpenID fields in the auth token payload:

Field Mandatory Datatype Description
sub Yes String <= 1024 bytes Unique identifier for the user
iss Yes URI URI of application responsible for issuing this token
exp Yes Epoch Timestamp Timestamp in seconds at when this token will be considered invalid
iat Yes Epoch Timestamp Timestamp in seconds when this token was issued and the data within loaded
auth_time No Epoch Timestamp Timestamp in seconds when the user last authenticated
aud Yes URI or list of URIs Must include https://api.doordeck.com
sid No String Session identifier
email No String User's email address
email_verified No (Defaults to false) Boolean Flag to specify if the user's email has been verified
telephone No E.164 User's phone number
telephone_verified No (Defaults to false) Boolean Flag to specify if the user's phone number has been verified
locale No BCP 47 User's locale (e.g. en-US)
zoneinfo No Timezone Timezone of user, e.g. Europe/London
name No String User's full name
family_name No String User's family name
middle_name No String User's middle name
given_name No String User's given name
picture No URI User's profile picture

Authentication tokens can be issued directly by Doordeck using the login endpoint or by third-party application developers using pre-registered asymmetric authentication keys.

Account

Login (v1)

curl 'https://api.doordeck.com/auth/token/'
  -X POST
  -H 'content-type: application/json'
  --data-binary '{"email":"EMAIL","password":"PASSWORD"}'

Make sure to replace USERNAME and PASSWORD with your credentials.

The above command returns JSON structured like this:

{
  "privateKey":"base 64 encoded private key",
  "publicKey":"base 64 encoded public key",
  "authToken":"JSON Web Token for authentication",
  "refreshToken":"JSON Web Token for refreshing authentication credentials"
}

This endpoint lets user's attempt to login.

HTTP Request

POST https://api.doordeck.com/auth/token

Request Parameters

Parameter Required Description
email true User's email address
password true User's password

Response

Parameter Description
privateKey PKCS8 encoded private key wrapped in base 64 encoding to be JSON friendly
publicKey Base 64 encoded public key
authToken JSON web token to be used for normal requests
refreshToken JSON web token to be used for getting new authentication tokens

Login (v2)

curl 'https://api.doordeck.com/auth/token/'
  -X POST
  -H "Accept: application/vnd.doordeck.api-v2+json"
  -H 'content-type: application/json'
  --data-binary '{"email":"EMAIL","password":"PASSWORD"}'

Make sure to replace USERNAME and PASSWORD with your credentials.

The above command returns JSON structured like this:

{
  "authToken":"JSON Web Token for authentication",
  "refreshToken":"JSON Web Token for refreshing authentication credentials"
}

This endpoint lets user's attempt to login.

HTTP Request

POST https://api.doordeck.com/auth/token

This call must be made with the Accept header set to application/vnd.doordeck.api-v2+json

Request Parameters

Parameter Required Description
email true User's email address
password true User's password

Response

Parameter Description
authToken JSON web token to be used for normal requests
refreshToken JSON web token to be used for getting new authentication tokens

Registration (v1)

curl "https://api.doordeck.com/auth/register"
  -X POST
  -H 'content-type: application/json'
  --data-binary '{"email":"EMAIL","password":"PASSWORD"}'

The above command returns JSON structured like this:

{
  "privateKey":"base 64 encoded private key",
  "publicKey":"base 64 encoded public key",
  "authToken":"JSON Web Token for authentication",
  "refreshToken":"JSON Web Token for refreshing authentication credentials"
}

This endpoint allows users to register for a Doordeck account.

HTTP Request

POST https://api.doordeck.com/auth/register

Request Parameters

Parameter Required Description
email true Email address to register.
password true Password for access to account.
displayName false User's display name (e.g. their fullname)

Registration (v2)

curl "https://api.doordeck.com/auth/register"
  -X POST
  -H "Accept: application/vnd.doordeck.api-v2+json"
  -H 'content-type: application/json'
  --data-binary '{"email":"EMAIL","password":"PASSWORD"}'

The above command returns JSON structured like this:

{
  "privateKey":"base 64 encoded private key",
  "publicKey":"base 64 encoded public key",
  "authToken":"JSON Web Token for authentication",
  "refreshToken":"JSON Web Token for refreshing authentication credentials"
}

This endpoint allows users to register for a Doordeck account; it's handling of accounts with a pending invite is different from v1 in that the call will fail with a 409 conflict error if there is a pending invite (unless force is set to true).

HTTP Request

POST https://api.doordeck.com/auth/register

This call must be made with the Accept header set to application/vnd.doordeck.api-v2+json

Request Parameters

Parameter Required Description
email true Email address to register.
password true Password for access to account.
displayName false User's display name (e.g. their fullname)

Query Parameters

Parameter Required Description
force false Boolean flag to indicate if a pending invite should be discarded and a new account created

Registration (v3)

curl "https://api.doordeck.com/auth/register"
  -X POST
  -H "Accept: application/vnd.doordeck.api-v3+json"
  -H 'content-type: application/json'
  --data-binary '{"email":"EMAIL","password":"PASSWORD"}'

The above command returns JSON structured like this:

{
  "authToken":"JSON Web Token for authentication",
  "refreshToken":"JSON Web Token for refreshing authentication credentials"
}

This endpoint allows users to register for a Doordeck account; the call will fail with a 409 conflict error if there is a pending invite (unless force is set to true).

This call differs from v2 by removing the privateKey and publicKey fields in favour of the ephemeral key registration endpoints.

HTTP Request

POST https://api.doordeck.com/auth/register

This call must be made with the Accept header set to application/vnd.doordeck.api-v3+json

Request Parameters

Parameter Required Description
email true Email address to register.
password true Password for access to account.
displayName false User's display name (e.g. their fullname)

Query Parameters

Parameter Required Description
force false Boolean flag to indicate if a pending invite should be discarded and a new account created

Refresh Token

curl -X POST "https://api.doordeck.com/auth/token/refresh"
  -H "Authorization: Bearer REFRESH_TOKEN"

The above command returns JSON structured like this:

  {
    "authToken":"JSON Web Token for authentication",
    "refreshToken":"(Optional) JSON Web Token for refreshing authentication credentials"
  }

This endpoint refreshes a users' authentication token using their refresh token. Refresh tokens cannot be used for standard requests and have a very long life compared with an authentication token.

HTTP Request

POST https://api.doordeck.com/auth/token/refresh

Logout

curl "https://api.doordeck.com/token/destroy"
  -H "Authorization: Bearer TOKEN"

This endpoint destroys a session associated with an authentication token and any associated refresh token.

HTTP Request

POST https://api.doordeck.com/token/destroy

Register Ephemeral Key

curl "https://api.doordeck.com/auth/certificate" \
  -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H 'content-type: application/json' \
  --data-binary '{"ephemeralKey":"Base64 encoded Ed25519 public key"}' 

Replace Base64 encoded Ed25519 public key with the user's ephemeral key.

The above command returns JSON structured like this:

  {
    "certificateChain": ["List of base64 encoded DER X509 certificates forming a complete certificate chain"],
    "userId": "Doordeck identifier for the user"
  }

This endpoint is used to register the ephemeral key for third-party application users', it returns a certificate chain with the user's key as the subject of the leaf certificate.

Only Ed25519 public keys are accepted by this endpoint, they can either be the native 32 byte public key Base 64 encoded or specified as a Base 64 DER encoded key as defined in RFC8410.

This endpoint may required a secondary authentication check before producing a certificate chain for the user, it will indicate this by returning a 423 error.

The certificate chain returned should be used in the x5c field when performing signed requests such as unlocking.

HTTP Request

POST https://api.doordeck.com/auth/certificate

Request Parameters

Parameter Required Description
ephemeralKey true Base64 encoded ephemeral Ed25519 key

Register Ephemeral Key With Secondary Authentication

curl "https://api.doordeck.com/auth/certificate/verify" \
  -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H 'content-type: application/json' \
  --data-binary '{"ephemeralKey":"Base64 encoded Ed25519 public key"}' 

Replace Base64 encoded Ed25519 public key with the user's ephemeral key.

The above command returns a HTTP 204

This endpoint is used to register ephemeral keys for users, it will start a secondary authentication flow using email, SMS, telephone or WhatsApp - the service will pick the most appropriate method based on the contents of the provided auth token or it can be specified as a query parameter.

HTTP Request

POST https://api.doordeck.com/auth/certificate/verify

Request Parameters

Parameter Required Description
ephemeralKey true Base64 encoded ephemeral Ed25519 key

Query Parameters

Parameter Required Description
method false One of EMAIL, TELEPHONE, SMS, WHATSAPP

Verify Ephemeral Key Registration

curl "https://api.doordeck.com/auth/certificate/check" \
  -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H 'content-type: application/json' \
  --data-binary '{"verificationSignature":"Base64 encoded Ed25519 signature of the authentication code"}' 

Replace Base64 encoded Ed25519 signature of the authentication code with a signature computed on the authentication code using the ephemeral key.

The above command returns JSON structured like this:

  {
    "certificateChain": ["List of base64 encoded DER X509 certificates forming a complete certificate chain"],
    "userId": "Doordeck identifier for the user"
  }

This endpoint is used to check the verification code sent to a use, it requires the ephemeral key sign the verification code so that Doordeck is sure the same ephemeral key is used.

HTTP Request

POST https://api.doordeck.com/auth/certificate/check

Request Parameters

Parameter Required Description
verificationSignature true Base64 encoded signature of the verification code with the ephemeral key

Verify Email

curl "https://api.doordeck.com/account/email/verify?code=CODE"
  -X PUT

Replace CODE with the verification code from the email.

This endpoint is used to verify a user's email address.

HTTP Request

PUT https://api.doordeck.com/account/email/verify

Query Parameters

Parameter Required Description
code true Verification code from email.

Reverify Email

curl "https://api.doordeck.com/account/email/reverify"
  -X POST
  -H "Authorization: Bearer TOKEN"

This endpoint will generate a new email to the logged user with a new verification code to validate their email address.

HTTP Request

POST https://api.doordeck.com/account/email/reverify

Change Password

curl "https://api.doordeck.com/account/password"
  -H "Authorization: Bearer TOKEN"
  -X POST
  -H 'content-type: application/json'
  --data-binary '{"oldPassword":"OLD_PASSWORD","newPassword":"NEW_PASSWORD"}'

Replace OLD_PASSWORD with the users' current password and NEW_PASSWORD with their desired password.

This endpoint is used to allow a user to change their password.

HTTP Request

POST https://api.doordeck.com/account/password

Request Parameters

Parameter Required Description
oldPassword true User's old password.
newPassword true User's desired new password.

Get User Details

curl "https://api.doordeck.com/account"
  -H "Authorization: Bearer TOKEN"

The above command returns JSON structured like this:

  {
    "publicKey": "User's public key",
    "email": "User's email address",
    "displayName": "User's display name",
    "emailVerified": true or false
  }

This endpoint returns information about the currently logged in user

HTTP Request

GET https://api.doordeck.com/account

Update User Details

curl "https://api.doordeck.com/account"
  -H "Authorization: Bearer TOKEN"
  -X POST
  -H 'content-type: application/json'
  --data-binary '{"displayName":"NEW_DISPLAY_NAME"}'

Replace NEW_DISPLAY_NAME with the new display name to use

This endpoint updates a user's details, currently this is limited to display name.

HTTP Request

POST https://api.doordeck.com/account

Request Parameters

Parameter Required Description
displayName true User's desired display name

Sites

List Sites

curl 'https://api.doordeck.com/site/'
  -H "Authorization: Bearer TOKEN"

The above command returns JSON structured like this:

[
    {
        "id": "b188b578-0035-11e8-ba89-0ed5f89f718b",
        "name": "IDEALondon",
        "logoUrl": null,
        "colour": "#666666",
        "longitude": -0.084819,
        "latitude": 51.521966,
        "radius": 20,
        "created": 1516709124.659,
        "updated": 1516709124.659
    },
    {
        "id": "7659e430-4a28-11e8-bf0b-bffab372a82e",
        "name": "Demo",
        "logoUrl": null,
        "colour": "#7AD651",
        "longitude": 0,
        "latitude": 0,
        "radius": 10,
        "created": 1524839827.955,
        "updated": 1524839827.955
    }
]

This endpoint lists all of the sites a user has access to.

HTTP Request

GET https://api.doordeck.com/site/

Get Locks For Site

curl 'https://api.doordeck.com/site/00000000-0000-0000-0000-000000000000/device/'
  -H "Authorization: Bearer TOKEN"

Replace 00000000-0000-0000-0000-000000000000 with the site's ID.

The above command returns JSON structured like this:

[
    {
        "id": "08aa7b70-30cf-11e8-ba42-6986d3c6ca8e",
        "name": "Demo #1",
        "colour": "#1F5468",
        "start": null,
        "end": null,
        "role": "ADMIN",
        "settings": {
            "unlockTime": 7,
            "permittedAddresses": [],
            "defaultName": "Demo #1",
            "usageRequirements": {},
            "unlockBetweenWindow": null,
            "tiles": [
                "403031a2-7869-4408-9f38-c71ae51b652b"
            ]
        },
        "state": {
            "connected": true
        },
        "favourite": false
    },
    {
        "id": "49b45c50-31da-11e8-8e0f-170748b9fca8",
        "name": "Demo #2",
        "colour": "#55678C",
        "start": null,
        "end": null,
        "role": "ADMIN",
        "settings": {
            "unlockTime": 7,
            "permittedAddresses": [],
            "defaultName": "Demo #2",
            "usageRequirements": {},
            "unlockBetweenWindow": null,
            "tiles": []
        },
        "state": {
            "locked": true,
            "connected": true
        },
        "favourite": false
    }
]

This endpoint lists all of the locks in a particular site that the user has access to.

HTTP Request

GET https://api.doordeck.com/site/SITE_ID/device/

Replace SITE_ID with the appropriate site ID.

Get Users For A Site

curl 'https://api.doordeck.com/site/00000000-0000-0000-0000-000000000000/user/'
  -H "Authorization: Bearer TOKEN"

Replace 00000000-0000-0000-0000-000000000000 with the site's ID.

The above command returns JSON structured like this:

[
    {
        "userId": "5b2b9930-3a7e-11e8-940e-bffab372a82e",
        "email": "michael@doordeck.com",
        "displayName": null,
        "orphan": false
    },
    {
        "userId": "f07d3ea0-593e-11e8-8257-bffab372a82e",
        "email": "john@doordeck.com",
        "displayName": null,
        "orphan": false
    }
]

This endpoint lists all users in the selected site, the results are filtered to ensure only locks the current user is an administrator of will return user information.

HTTP Request

GET https://api.doordeck.com/site/SITE_ID/user/

Replace SITE_ID with the appropriate site ID.

Tiles

Get Lock Belonging To Tile

curl 'https://api.doordeck.com/tile/00000000-0000-0000-0000-000000000000/'
  -H "Authorization: Bearer TOKEN"

Replace 00000000-0000-0000-0000-000000000000 with the tile ID.

The above command returns 404 if no tile is known, or a see other 303 with the Location header set to the value of the lock

This endpoint identifies which lock belongs to the specific tile.

HTTP Request

GET https://api.doordeck.com/tile/TILE_ID/

Replace TILE_ID with the appropriate tile ID.

Associate Tile With Lock

curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000/tile/00000000-0000-0000-0000-000000000001'
  -X PUT
  -H "Authorization: Bearer TOKEN"

Replace 00000000-0000-0000-0000-000000000000 with the device ID.

Replace 00000000-0000-0000-0000-000000000001 with the tile ID.

The endpoints links a tile to a lock; the current user must be an administrator of the lock and the tile must not be associated to any other locks.

HTTP Request

PUT https://api.doordeck.com/device/DEVICE_ID/tile/TILE_ID/

Replace TILE_ID with the appropriate tile ID and DEVICE_ID with the appropriate device ID.

Disassociate Tile From Lock

curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000/tile/00000000-0000-0000-0000-000000000001'
  -X DELETE
  -H "Authorization: Bearer TOKEN"

Replace 00000000-0000-0000-0000-000000000000 with the device ID.

Replace 00000000-0000-0000-0000-000000000001 with the tile ID.

The endpoint removes the relationship between a tile and a lock, the tile can then be reassigned to another lock.

HTTP Request

DELETE https://api.doordeck.com/device/DEVICE_ID/tile/TILE_ID/

Replace TILE_ID with the appropriate tile ID and DEVICE_ID with the appropriate device ID.

Lock Operations

Get All Locks

curl 'https://api.doordeck.com/device'
  -H "Authorization: Bearer TOKEN"

The above command returns JSON structured like this:

[
  {
    "id":"00000000-0000-0000-0000-000000000000",
    "name":"Home",
    "lastOperation": 1494786493,
    "colour": "#57355D",
    "role": "ADMIN",
    "settings": 
      {
        "txBeaconRssi": -45,
        "rxBeaconRssi": -80,
        "unlockTime": 10,
        "proximityUnlock": true,
        "permittedAddresses": [],
        "defaultName": "Home",
        "usageRequirements": {},
        "delay": 0
      },
    "state":
      {
        "locked":true,
        "connected":true,
        "duration":10
      },
    "favourite": true,
    "unlockTime":10,
    "unlockForever":false
  },
  {
    "id":"00000000-0000-0000-0000-000000000001",
    "name":"Office",
    "lastOperation": 1494786333,
    "colour": "#FFAACC",
    "role": "USER",
    "settings": 
      {
        "txBeaconRssi": 0,
        "rxBeaconRssi": 0,
        "unlockTime": 5,
        "proximityUnlock": false,
        "permittedAddresses": [
          "33.44.55.66"
        ],
        "defaultName": "Super office",
        "usageRequirements": {},
        "delay": 0,
        "unlockBetweenWindow": {
          "start": "08:00",
          "end": "14:35",
          "timezone": "Europe/London",
          "days": [
            "WEDNESDAY"
          ],
          "exceptions": []
        }
      },
    "state":
      {
        "locked":true,
        "connected":true,
        "duration":5
      },
    "favourite": true,
    "unlockTime":5,
    "unlockForever":false,
    "start":null,
    "end":null
  }
]

This endpoint retrieves all locks a user has access to.

HTTP Request

GET https://api.doordeck.com/device

Get A Single Lock

curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000'
  -H "Authorization: Bearer TOKEN"

Replace 00000000-0000-0000-0000-000000000000 with the lock's ID.

The above command returns JSON structured like this:

{
  "id": "00000000-0000-0000-0000-000000000001",
  "name": "Home",
  "lastOperation": 1494786493,
  "colour": "#57355D",
  "role": "ADMIN",
  "settings": {
    "txBeaconRssi": -45,
    "rxBeaconRssi": -80,
    "unlockTime": 10,
    "proximityUnlock": true,
    "permittedAddresses": [],
    "defaultName": "Home",
    "usageRequirements": {},
    "delay": 0,
    "unlockBetweenWindow": {
      "start": "08:00",
      "end": "14:35",
      "timezone": "Europe/London",
      "days": [
        "WEDNESDAY"
      ],
      "exceptions": []
    }
  },
  "state": {
    "locked": true,
    "connected": true,
    "duration": 10
  },
  "favourite": true,
  "unlockTime": 10,
  "unlockForever": false,
  "start":null,
  "end":null
}

This endpoint retrieves information about a specific lock, its usage is preferred over the list lock call for performance reasons.

HTTP Request

GET https://api.doordeck.com/device/LOCK_ID

Replace LOCK_ID with the appropriate lock ID.

Get Lock Audit Trail (v1)

curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000/log'
  -H "Authorization: Bearer TOKEN"

Replace 00000000-0000-0000-0000-000000000000 with the lock's ID.

The above command returns JSON structured like this:

[
  {
    "timestamp":1473061669.000000000,
    "type":"DOOR_LOCK",
    "user":null,
    "message":"Door locked"
  },
  {
    "timestamp":1473061664.000000000,
    "type":"DOOR_UNLOCK",
    "user":null,
    "message":"Door unlocked"
  }
]

This endpoint retrieves all log events associated with a particular lock.

HTTP Request

GET https://api.doordeck.com/device/LOCK_ID/log

Replace LOCK_ID with the appropriate lock ID.

Event Types

The call returns an enum of event types:

Type Description
DOOR_OPEN The lock's monitor shows the door is open
DOOR_CLOSE The lock's monitor shows the door is closed
DOOR_UNLOCK The lock has changed to the unlock stated
DOOR_LOCK The lock has changed to the locked state
OWNER_ASSIGNED The lock's owner has been updated
DEVICE_CONNECTED Lock has connected to Doordeck platform
DEVICE_DISCONNECTED Lock has disconected from Doordeck platform

Get Lock Audit Trail (v2)

curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000/log'
  -H "Accept: application/vnd.doordeck.api-v2+json"
  -H "Authorization: Bearer TOKEN"

Replace 00000000-0000-0000-0000-000000000000 with the lock's ID.

The above command returns JSON structured like this:

[
  {
    "timestamp": 1494267549,
    "type": "DOOR_LOCK",
    "user": null,
    "email": null,
    "displayName": null,
    "message": "Door locked"
  },
  {
    "timestamp": 1494267539,
    "type": "DOOR_UNLOCK",
    "user": null,
    "email": null,
    "displayName": null,
    "message": "Door unlocked"
  },
  {
    "timestamp": 1494267534,
    "type": "DOOR_UNLOCK",
    "user": "00000000-0000-0000-0000-000000000000",
    "email": "info@doordeck.com",
    "displayName": "Doordeck User",
    "message": "Door unlocked"
  }
]

This endpoint retrieves all log events associated with a particular lock, it includes additional details over v1.

HTTP Request

GET https://api.doordeck.com/device/LOCK_ID/log

Replace LOCK_ID with the appropriate lock ID.

This call must be made with the Accept header set to application/vnd.doordeck.api-v2+json

Event Types

The call returns an enum of event types:

Type Description
DOOR_OPEN The lock's monitor shows the door is open
DOOR_CLOSE The lock's monitor shows the door is closed
DOOR_UNLOCK The lock has changed to the unlock stated
DOOR_LOCK The lock has changed to the locked state
OWNER_ASSIGNED The lock's owner has been updated
DEVICE_CONNECTED Lock has connected to Doordeck platform
DEVICE_DISCONNECTED Lock has disconected from Doordeck platform
LOCK_SHARED The lock's access has been shared to a new user
LOCK_REVOKED Access to the lock has been revoked for the specified user
USER_PROMOTED A user was promoted to an administrator
USER_DEMOTED An administrator was demoted to a user

Get Audit For A User

curl 'https://api.doordeck.com/user/00000000-0000-0000-0000-000000000000/log'
  -H "Accept: application/vnd.doordeck.api-v2+json"
  -H "Authorization: Bearer TOKEN"

Replace 00000000-0000-0000-0000-000000000000 with the user's ID.

The above command returns JSON structured like this:

[
  {
    "deviceId": "00000000-0000-0000-0000-000000000001",
    "timestamp": 1509481411,
    "type": "LOCK_SHARED",
    "issuer": {
      "userId": "00000000-0000-0000-0000-000000000002"
    },
    "subject": {
      "userId": "00000000-0000-0000-0000-000000000003",
      "email": "info@doordeck.com"
    },
    "rejected": false
  },
  {
    "deviceId": "00000000-0000-0000-0000-000000000001",
    "timestamp": 1509035275,
    "type": "DOOR_UNLOCK",
    "issuer": {
      "userId": "00000000-0000-0000-0000-000000000002"
    },
    "rejected": false
  }
]

This endpoint retrieves all log events associated with a particular user, it uses the same events as listed in the v2 audit trail endpoint.

HTTP Request

GET https://api.doordeck.com/user/LOCK_ID/log

Replace LOCK_ID with the appropriate lock ID.

Get Users For A Lock

curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000/users'
  -H "Authorization: Bearer TOKEN"

Replace 00000000-0000-0000-0000-000000000000 with the lock's ID.

The above command returns JSON structured like this:

[
  {
    "userId": "00000000-0000-0000-0000-000000000000",
    "email": "developer@doordeck.com.com",
    "publicKey": "base 64 encoded public key",
    "displayName": "Developer",
    "orphan": false,
    "role": "USER"
  },
  {
    "userId": "00000000-0000-0000-0000-000000000001",
    "email": "administrator@doordeck.com",
    "publicKey": "base 64 encoded public key",
    "displayName": "Administrator",
    "orphan": false,
    "role": "ADMIN"
  }
]

This endpoint retrieves all users associated with a particular lock.

HTTP Request

GET https://api.doordeck.com/device/LOCK_ID/users

Replace LOCK_ID with the appropriate lock ID.

Get Locks For A User

 curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000'

Replace 00000000-0000-0000-0000-000000000000 with the user's ID.

The above command returns JSON structured like this:

{
    "userId": "5a5e6e70-3c51-11e6-9e57-cf40be3013fb",
    "email": "michael@doordeck.com",
    "publicKey": "base 64 encoded public key",
    "displayName": "Michael Barnwell",
    "orphan": false,
    "devices": [
        {
            "deviceId": "ba8fb900-4def-11e8-9370-170748b9fca8",
            "role": "ADMIN"
        },
        {
            "deviceId": "e378ebe0-45f9-11e7-a620-79be7967fabd",
            "role": "ADMIN"
        },
        {
            "deviceId": "eeb74c90-7c1e-11e7-9823-a9f736dac766",
            "role": "ADMIN"
        }
    ]
}

This endpoint returns basic user information, including the user's public key and a list of the locks that the user is enrolled on, the list will only show locks where the current user is an administrator.

HTTP Request

GET https://api.doordeck.com/user/USER_ID/

Replace USER_ID with the appropriate user ID.

Update Lock Properties

curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000'
  -X PUT
  -H "Authorization: Bearer TOKEN"
  -H 'content-type: application/json'
  --data-binary '{"name":"Home","favourite":false,"colour":"#ffggaa"}'

Replace 00000000-0000-0000-0000-000000000000 with the lock's ID.

This endpoint allows the name, favourite flag and colour to be updated for an existing lock.

HTTP Request

PUT https://api.doordeck.com/device/LOCK_ID

Replace LOCK_ID with the appropriate lock ID.

Request Parameters

Parameter Required Description
name false Update the user's alias for the lock
favourite false Flag the lock as a favourite
colour false Update the colour of the lock
settings false Update global settings for the lock

The settings object is formed of the following fields

Parameter Required Description
txBeaconRssi false Update the iBeacon sensitivity (Deprecated)
rxBeaconRssi false Update the iBeacon sensitivity (Deprecated)
proximityUnlock false Control if the lock can be unlocked via a touch action (Deprecated)
defaultName false Set the default name for all users who have not set a custom alias
permittedAddress false A complete list of permitted IP addresses for performing actions on the door (public IP addresses)
delay false A time in milliseconds to delay the UI countdown action, for slow locks (Deprecated)
usageRequirements false An object containing usage requirements of the lock, see below.

The usage requirements is formed of the following fields

Parameter Required Description
time False List of time requirements, see time requirement definition below.
location False GPS restriction, see location requirement definition below.

The time requirements is formed of a list, each containing the following fields

Parameter Required Description
start true Local time, (HH:mm) describing the start of a permitted time window
end true Local time, (HH:mm) describing the end of a permitted time window
timezone true Timezone, e.g. Europe/London, describing what hours the start and end are valid in
days true List of days the time window applies, e.g. MONDAY, TUESDAY

The location requirements is formed of the following fields

Parameter Required Description
latitude true Latitude of the center point
longitude true Longitude of the center point
enabled false Flag indicating if the location requirement is enabled
radius false Indicates what size the bubble should be where the location is considered matched, defaults to 100m
accuracy false Indicates how accurate the phone's GPS must be to be considered matched, defaults to 200m

Pair With New Lock

curl 'https://api.doordeck.com/device'
  -X POST
  -H 'Authorization: Bearer TOKEN'
  -H 'content-type: application/json'
  --data-binary '{"key":"KEY","name":"My lock"}'

Replace KEY with the lock's registration key

This endpoint pairs a new, previously unowned lock with a user.

HTTP Request

POST https://api.doordeck.com/device

Request Parameters

Parameter Required Description
key true Lock's registration key
name true Alias of the lock (default for all users)

Get A Doordeck User’s Public Key

This endpoint allows the retrieval of a user's public key along with their ID.

curl 'https://api.doordeck.com/share/invite/USER_EMAIL' \
  -X POST \
  -H 'authorization: Bearer TOKEN' \
  -H 'content-type: application/json' 
  • Replace USER_EMAIL with the user's email

The above command returns JSON structured like this:

{
  "id":"00000000-0000-0000-0000-000000000000",
  "publicKey":"base 64 encoded public key"
}

HTTP Request

GET https://api.doordeck.com/share/invite/USER_EMAIL

Replace USER_EMAIL with the user's email

Get A Third-Party User’s Public Key

This endpoint allows retrieval of a user's public key, it provides flexibility to third-party application developers by allowing querying via email, telephone, user identifier (both internal and external) and by complete identity (encrypted).

Queries against this endpoint are restricted by the third-party's user pool, in other words, this call will only return users belonging to the same application as specified in the auth token.

This endpoint accepts a single JSON key (multiple keys cannot be used) which can be one of the following:

Field Description
email Email address
telephone E.164 formatted telephone
localKey Doordeck identifier for a user (UUID)
foreignKey Third-party application's identifier for a user
identity Encrypted OpenID token of user

The first four query keys, email, telephone, localKey and foreignKey are read only - these will return a 404 error if the user is not known to Doordeck.

The remaining query key, identity, is used to specify the full identity of the user who is the subject of the query, this will mean the user is created if they don't exist and will always return a response. When using identity, the specified OpenID token must be encrypted so it cannot be abused as an authentication token - it should be encrypted using JSON Web Encryption (JWE) using the RSA key Doordeck generates for the particular third-party application.

curl 'https://api.doordeck.com/directory/query' \
  -X POST \
  -H 'authorization: Bearer TOKEN' \
  -H 'content-type: application/json' \
  --data-binary '{"email":"USER_EMAIL"}'
  • Replace USER_EMAIL with the user's email

The above command returns JSON structured like this:

{
  "id":"00000000-0000-0000-0000-000000000000",
  "publicKey":"base 64 encoded public key"
}

HTTP Request

POST https://api.doordeck.com/directory/query

Request Parameters

The request body must have one and only one of the following fields.

Parameter Required Description
email false Email address
telephone false E.164 formatted telephone
localKey false Doordeck identifier for a user (UUID)
foreignKey false Third-party application's identifier for a user
identity false Encrypted OpenID token of user

Unlock

curl 'https://api.doordeck.com/auth/token/' \
  -X POST \
  -H 'content-type: application/json' \
  --data-binary '{"email":"USERNAME","password":"PASSWORD"}' \
  | jq -r .privateKey \
  | base64 --decode \
  | openssl pkcs8 -nocrypt -inform DER -outform PEM -out privatekey.pem

HEADER='{"alg":"RS256","typ":"JWT"}'
BODY='{"iss":"USER_ID","sub":"00000000-0000-0000-0000-000000000000","nbf":1473083829,"iat":1473083829,"exp":1473083889,"operation":{"type":"MUTATE_LOCK","locked":false,"duration":5}}'
HEADER_B64=`echo -n $HEADER | base64 | sed 's/+/-/g;s/\//_/g;s/=//g'`
BODY_B64=`echo -n $BODY | base64  | sed 's/+/-/g;s/\//_/g;s/=//g'`
SIGNATURE_B64=`echo -n $HEADER_B64.$BODY_B64 | openssl sha -sha256 -sign privatekey.pem | base64 | sed 's/+/-/g;s/\//_/g;s/=//g'`
JWT=`echo -n $HEADER_B64.$BODY_B64.$SIGNATURE_B64`

curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000/execute'
  -X POST
  -H 'authorization: Bearer TOKEN'
  -H 'content-type: application/json;charset=UTF-8'
  --data-binary "$JWT"

Replace 00000000-0000-0000-0000-000000000000 with the lock's ID, USER_ID with the user's ID (obtained from decoding their auth token), USERNAME and PASSWORD with the appropriate credentials.

This endpoint allows a device to be unlocked. Requests to this endpoint must be signed and formed as a JSON web token.

HTTP Request

POST https://api.doordeck.com/device/LOCK_ID/execute

Replace LOCK_ID with the appropriate lock ID.

Request Parameters

The header is formed of the following fields.

Parameter Required Description
alg true RS256 (legacy) RSA signed with a 256 bit SHA hash, or EdDSA for ephemeral key signatures
x5c false User's certificate chain, mandatory for EdDSA signatures
typ true JWT, JSON web token

The body is formed of the following fields.

Parameter Required Description
iss true Issuer, this should be the user's ID
sub true Subject, this should be the lock's ID
nbf true Not before, a Unix timestamp indicating the earliest date the request is valid from
iat true Issued at, the current Unix timestamp
exp true Expires, a Unix timestamp indicating when the request should expire, requests to change the lock status should be valid for up to one minute, other requests can have a much longer expiry time
jti false (but highly recommended) User generated, unique ID used for tracking the request status and preventing replay attacks. UUIDs are recommended here.
operation true A JSON object containing the instructions of the lock

The operation object definition is as follows

Parameter Required Description
type true Must be MUTATE_LOCK
locked true Boolean indicating if the lock should be locked or unlocked

Share A Lock

curl 'https://api.doordeck.com/auth/token/' \
  -X POST \
  -H 'content-type: application/json' \
  --data-binary '{"email":"USERNAME","password":"PASSWORD"}' \
  | jq -r .privateKey \
  | base64 --decode \
  | openssl pkcs8 -nocrypt -inform DER -outform PEM -out privatekey.pem

HEADER='{"alg":"RS256","typ":"JWT"}'
BODY='{"iss":"USER_ID","sub":"00000000-0000-0000-0000-000000000000","nbf":1473083829,"iat":1473083829,"exp":1473083889,"operation":{"type":"ADD_USER","publicKey":PUBLIC_KEY,"user":"11111111-1111-1111-1111-111111111111","role":"USER","start":START_TIME,"end":END_TIME}}'
HEADER_B64=`echo -n $HEADER | base64 | sed 's/+/-/g;s/\//_/g;s/=//g'`
BODY_B64=`echo -n $BODY | base64  | sed 's/+/-/g;s/\//_/g;s/=//g'`
SIGNATURE_B64=`echo -n $HEADER_B64.$BODY_B64 | openssl sha -sha256 -sign privatekey.pem | base64 | sed 's/+/-/g;s/\//_/g;s/=//g'`
JWT=`echo -n $HEADER_B64.$BODY_B64.$SIGNATURE_B64`

curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000/execute'
  -X POST
  -H 'authorization: Bearer TOKEN'
  -H 'content-type: application/json;charset=UTF-8'
  --data-binary "$JWT"
  • Replace 00000000-0000-0000-0000-000000000000 with the lock's ID
  • Replace USER_ID with the user's ID (obtained from decoding their auth token)
  • Replace PUBLIC_KEY with the invitee's public key
  • Replace 11111111-1111-1111-1111-111111111111 with the invitee's user ID,
  • Replace USERNAME and PASSWORD with the appropriate credentials
  • Replace START_TIME and END_TIME with Unix timestamps of when the user should be activate from and until, use null for indefinite

This endpoint allows operations to be performed on a lock, such as lock, unlock, add/remove user. Requests to this endpoint must be signed and formed as a JSON web token.

HTTP Request

POST https://api.doordeck.com/device/LOCK_ID/execute

Replace LOCK_ID with the appropriate lock ID.

Request Parameters

The header is formed of the following fields.

Parameter Required Description
alg true RS256 (legacy) RSA signed with a 256 bit SHA hash, or EdDSA for ephemeral key signatures
x5c false User's certificate chain, mandatory for EdDSA signatures
typ true JWT, JSON web token

The body is formed of the following fields.

Parameter Required Description
iss true Issuer, this should be the user's ID
sub true Subject, this should be the lock's ID
nbf true Not before, a Unix timestamp indicating the earliest date the request is valid from
iat true Issued at, the current Unix timestamp
exp true Expires, a Unix timestamp indicating when the request should expire, requests to change the lock status should be valid for up to one minute, other requests can have a much longer expiry time
jti false (but highly recommended) User generated, unique ID used for tracking the request status and preventing replay attacks. UUIDs are recommended here.
operation true A JSON object containing the instructions of the lock

The operation object definition is as follows

Parameter Required Description
type true Must be ADD_USER
user true ID of user to add
publicKey true Public key of user to add
role false Should be either ADMIN or USER
start false Unix timestamp of when the user should be active from, null or unset to start immediately
end false Unix timestamp of when the user should expire, null or unset for never expires

Revoke Access To A Lock

curl 'https://api.doordeck.com/auth/token/' \
  -X POST \
  -H 'content-type: application/json' \
  --data-binary '{"email":"USERNAME","password":"PASSWORD"}' \
  | jq -r .privateKey \
  | base64 --decode \
  | openssl pkcs8 -nocrypt -inform DER -outform PEM -out privatekey.pem

HEADER='{"alg":"RS256","typ":"JWT"}'
BODY='{"iss":"USER_ID","sub":"00000000-0000-0000-0000-000000000000","nbf":1473083829,"iat":1473083829,"exp":1473083889,"operation":{"type":"REMOVE_USER","users":["11111111-1111-1111-1111-111111111111"]}}'
HEADER_B64=`echo -n $HEADER | base64 | sed 's/+/-/g;s/\//_/g;s/=//g'`
BODY_B64=`echo -n $BODY | base64  | sed 's/+/-/g;s/\//_/g;s/=//g'`
SIGNATURE_B64=`echo -n $HEADER_B64.$BODY_B64 | openssl sha -sha256 -sign privatekey.pem | base64 | sed 's/+/-/g;s/\//_/g;s/=//g'`
JWT=`echo -n $HEADER_B64.$BODY_B64.$SIGNATURE_B64`

curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000/execute'
  -X POST
  -H 'authorization: Bearer TOKEN'
  -H 'content-type: application/json;charset=UTF-8'
  --data-binary "$JWT"
  • Replace 00000000-0000-0000-0000-000000000000 with the lock's ID
  • Replace USER_ID with the user's ID (obtained from decoding their auth token)
  • Replace 11111111-1111-1111-1111-111111111111 with the revoked user's ID,
  • Replace USERNAME and PASSWORD with the appropriate credentials

This endpoint allows multiple operations to be performed on locks. Requests to this endpoint must be signed and formed as a JSON web token. This section explains how to revoke access to a lock, this can also be used to delete a lock from the current users account.

HTTP Request

POST https://api.doordeck.com/device/LOCK_ID/execute

Replace LOCK_ID with the appropriate lock ID.

Request Parameters

The header is formed of the following fields.

Parameter Required Description
alg true RS256 (legacy) RSA signed with a 256 bit SHA hash, or EdDSA for ephemeral key signatures
x5c false User's certificate chain, mandatory for EdDSA signatures
typ true JWT, JSON web token

The body is formed of the following fields.

Parameter Required Description
iss true Issuer, this should be the user's ID
sub true Subject, this should be the lock's ID
nbf true Not before, a Unix timestamp indicating the earliest date the request is valid from
iat true Issued at, the current Unix timestamp
exp true Expires, a Unix timestamp indicating when the request should expire, requests to change the lock status should be valid for up to one minute, other requests can have a much longer expiry time
jti false (but highly recommended) User generated, unique ID used for tracking the request status and preventing replay attacks. UUIDs are recommended here.
operation true A JSON object containing the instructions of the lock

The operation object definition is as follows

Parameter Required Description
type true Must be REMOVE_USER
users true List of user IDs to remove

Update Secure Settings

curl 'https://api.doordeck.com/auth/token/' \
  -X POST \
  -H 'content-type: application/json' \
  --data-binary '{"email":"USERNAME","password":"PASSWORD"}' \
  | jq -r .privateKey \
  | base64 --decode \
  | openssl pkcs8 -nocrypt -inform DER -outform PEM -out privatekey.pem

HEADER='{"alg":"RS256","typ":"JWT"}'
BODY='{"iss":"USER_ID","sub":"00000000-0000-0000-0000-000000000000","nbf":1473083829,"iat":1473083829,"exp":1473083889,"operation":{"type":"MUTATE_SETTING","unlockDuration":10}}'
HEADER_B64=`echo -n $HEADER | base64 | sed 's/+/-/g;s/\//_/g;s/=//g'`
BODY_B64=`echo -n $BODY | base64  | sed 's/+/-/g;s/\//_/g;s/=//g'`
SIGNATURE_B64=`echo -n $HEADER_B64.$BODY_B64 | openssl sha -sha256 -sign privatekey.pem | base64 | sed 's/+/-/g;s/\//_/g;s/=//g'`
JWT=`echo -n $HEADER_B64.$BODY_B64.$SIGNATURE_B64`

curl 'https://api.doordeck.com/device/00000000-0000-0000-0000-000000000000/execute'
  -X POST
  -H 'authorization: Bearer TOKEN'
  -H 'content-type: application/json;charset=UTF-8'
  --data-binary "$JWT"
  • Replace 00000000-0000-0000-0000-000000000000 with the lock's ID
  • Replace USER_ID with the user's ID (obtained from decoding their auth token)
  • Replace 11111111-1111-1111-1111-111111111111 with the revoked user's ID,
  • Replace USERNAME and PASSWORD with the appropriate credentials

This endpoint allows multiple operations to be performed on locks. Requests to this endpoint must be signed and formed as a JSON web token. This section explains how to change on-lock settings, such as unlock time and open hours.

HTTP Request

POST https://api.doordeck.com/device/LOCK_ID/execute

Replace LOCK_ID with the appropriate lock ID.

Request Parameters

The header is formed of the following fields.

Parameter Required Description
alg true RS256 (legacy) RSA signed with a 256 bit SHA hash, or EdDSA for ephemeral key signatures
x5c false User's certificate chain, mandatory for EdDSA signatures
typ true JWT, JSON web token

The body is formed of the following fields.

Parameter Required Description
iss true Issuer, this should be the user's ID
sub true Subject, this should be the lock's ID
nbf true Not before, a Unix timestamp indicating the earliest date the request is valid from
iat true Issued at, the current Unix timestamp
exp true Expires, a Unix timestamp indicating when the request should expire, requests to change the lock status should be valid for up to one minute, other requests can have a much longer expiry time
jti false (but highly recommended) User generated, unique ID used for tracking the request status and preventing replay attacks. UUIDs are recommended here.
operation true A JSON object containing the instructions of the lock

The operation object definition is as follows

Parameter Required Description
type true Must be MUTATE_SETTING
unlockDuration false Set to an integer number of seconds for the lock to remain unlocked
unlockBetween false Set to unlock between definition below, or null to remove settings

The unlock between object definition is as follows

Parameter Required Description
start true Local time, (HH:mm) describing the start of an unlock between time window
end true Local time, (HH:mm) describing the end of an unlock between time window
timezone true Timezone, e.g. Europe/London, describing what hours the start and end are valid in
days true List of days the time window applies, e.g. MONDAY, TUESDAY
exceptions false List of dates (YYYY-MM-DD) to ignore above settings, useful for holidays

Monitor Real-time Lock State

curl "https://api.doordeck.com/device/events?device=00000000-0000-0000-0000-000000000000"
  -H "Authorization: Bearer TOKEN"

Replace 00000000-0000-0000-0000-000000000000 with the lock's ID

This is a Server-Sent Events endpoint that takes multiple devices and returns a stream of events.

HTTP Request

GET https://api.doordeck.com/device/events?device=00000000-0000-0000-0000-000000000000

Query Parameters

Parameter Required Description
device true Device ID to monitor, multiple can specified as separate query parameters

Get Pinned Locks

curl "https://api.doordeck.com/device/favourite"
  -H "Authorization: Bearer TOKEN"

The above command returns JSON structured like this:

[
    {
        "id": "3cc19730-4603-11e7-a620-79be7967fabd",
        "name": "Reception",
        "colour": "#24BD9A",
        "start": null,
        "end": null,
        "role": "USER",
        "settings": {
            "unlockTime": 5,
            "permittedAddresses": [],
            "defaultName": "Reception",
            "usageRequirements": {},
            "unlockBetweenWindow": null,
            "tiles": [
                "3cc19730-4603-11e7-a620-79be7967fabd"
            ]
        },
        "state": {
            "locked": true,
            "connected": true
        },
        "favourite": true
    },
    {
        "id": "ad8fb800-4def-11e8-9370-170748b9fca8",
        "name": "Web Demo",
        "colour": "#D93951",
        "start": null,
        "end": null,
        "role": "ADMIN",
        "settings": {
            "unlockTime": 7,
            "permittedAddresses": [],
            "defaultName": "Web Demo",
            "usageRequirements": {},
            "unlockBetweenWindow": null,
            "tiles": []
        },
        "state": {
            "locked": true,
            "connected": true
        },
        "favourite": true
    }
]

The endpoint returns a list of the current user's pinned locks.

HTTP Request

GET https://api.doordeck.com/device/favourite

Get Shareable Locks

curl "https://api.doordeck.com/device/shareable"
  -H "Authorization: Bearer TOKEN"

The above command returns JSON structured like this:

[
    {
        "id": "08aa6b81-30cf-11e8-ba42-6986d3c6ca8e",
        "name": "Demo #1"
    },
    {
        "id": "48dceebb-31cf-11e8-a9fe-6986d3c6ca8e",
        "name": "Demo #2"
    }
]

This endpoint returns the names and IDs of locks where the current user is an administrator.

HTTP Request

GET https://api.doordeck.com/device/shareable

Platform

Create Application

curl 'https://api.doordeck.com/platform/application'
  -X POST
  -H "Authorization: Bearer TOKEN"
  -H 'content-type: application/json'
  --data-binary '{"name":"My Amazing App","companyName":"My amazing company","mailingAddress":"My address"}'

This endpoint allows the creation of an application; an application is how user's are divided between third-parties within Doordeck and define certain branding, UI and authentication elements.

The user creating the application will automatically be assigned as the owner.

HTTP Request

POST https://api.doordeck.com/platform/application

Request Parameters

Parameter Required Description
name true Application's name
companyName true Company's registered name, e.g. Doordeck Limited
mailingAddress true Company's registered address, e.g. IDEALondon, 69 Wilson Street, LONDON, EC2A 2BB
privacyPolicy false URI to the application's privacy policy, must start with https://
supportContact false URI to application's support contact, can start with https:// or mailto://
appLink false URI for deep linking into the application directly
emailPreferences false See email preference definition below
logoUrl false URI to application's logo, must be hosted on https://cdn.doordeck.com/

The email preferences object is formed of the following fields

Parameter Required Description
senderEmail false (defaults to info@doordeck.com) Email address to use when sending emails to users'
senderName false (defaults to Doordeck) Email name to use when emailing users'
primaryColour false (defaults to #00283C) Primary colouring for email
secondaryColour false (defaults to #45BDD1) Secondary colouring for email
callToAction false See call to action definition

The call to action is formed of the following fields

Parameter Required Description
actionTarget true URI to direct user's to when clicking CTA
headline true Textual description for CTA, e.g. "Use the Doordeck App to make unlocking a breeze!"
actionText true Text used for the CTA button, e.g. "Download now!"

List Applications

curl 'https://api.doordeck.com/platform/application' \
  -X GET \
  -H "Authorization: Bearer TOKEN"

Lists all application's owned by the current user

HTTP Request

GET https://api.doordeck.com/platform/application

Get Application

curl 'https://api.doordeck.com/platform/application/APPLICATION_ID' \
  -X GET \
  -H "Authorization: Bearer TOKEN"

Replace APPLICATION_ID with the application ID.

Get's the application specified by application ID.

HTTP Request

GET https://api.doordeck.com/platform/application/APPLICATION_ID

Update Application

Updates any of the fields defined in the initial create application request.

HTTP Request

POST https://api.doordeck.com/platform/application/APPLICATION_ID

Delete Application

Delete's the application, this is irreversible!

HTTP Request

DELETE https://api.doordeck.com/platform/application/APPLICATION_ID

Get Logo Upload URL

Gets a pre-signed URL ready for uploading the application logo to.

HTTP Request

POST https://api.doordeck.com/platform/application/APPLICATION_ID/logo

Request Parameters

Parameter Required Description
contentType true Content-type of the logo, e.g. image/png

Add Auth Key

Adds a new auth key to the permitted auth keys for user's of this application, can be RSA, EC or Ed25519.

HTTP Request

POST https://api.doordeck.com/platform/application/APPLICATION_ID/key

Request Parameters

Key should be in JSON Web Key format (JWK), key must have a unique key ID (kid) field.

 Add Auth Issuer

Adds a new auth issuer which must be unique across all applications, it should be a URI controller by the application itself, e.g. https://myapp.com - it must match the iss field in all auth tokens generated by the third-party application.

HTTP Request

POST https://api.doordeck.com/platform/application/APPLICATION_ID/issuer

Request Parameters

Parameter Required Description
url true Issuer

Delete Auth Issuer

Deletes an auth issuer.

HTTP Request

DELETE https://api.doordeck.com/platform/application/APPLICATION_ID/issuer

Request Parameters

Parameter Required Description
url true Issuer

 Add CORS Domain

Adds a domain to the list of permitted CORS domains to allow webapps to call Doordeck APIs directly.

HTTP Request

POST https://api.doordeck.com/platform/application/APPLICATION_ID/cors

Request Parameters

Parameter Required Description
url true CORS Domain

Remove CORS Domain

Remove CORS domain.

HTTP Request

DELETE https://api.doordeck.com/platform/application/APPLICATION_ID/cors

Request Parameters

Parameter Required Description
url true CORS Domain

Encoding

Versioning

All Doordeck endpoints use JSON as their primary encoding scheme and respond to clients sending an Accept: application/json header, when a newer endpoints are available, clients should specify Accept: application/vnd.doordeck.api-v2+json (replacing v2 with v3, etc).

Certificate & Asymmetric Keys

Where certificates or keys are specified, these are in a BASE64 encoded DER format - DER is a binary encoding using ASN.1 and is commonly understood by most cryptographic libraries.

BASE64 encoded DER strings are very similar to PEM encoded values and can be converted by adding the appropriate PEM header and footer and by adding a newline character every 64 characters, e.g.

-----BEGIN PUBLIC KEY-----
BASE64 DER PUBLIC KEY
-----END PUBLIC KEY-----

Errors

The Doordeck API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is wrong
401 Unauthorized -- Your API key is wrong
403 Forbidden -- You don't have permission
404 Not Found -- The specified resource could not be found
405 Method Not Allowed -- You tried to access a resource with an invalid method
406 Not Acceptable -- You requested a format that isn't json
409 Conflict - The JWT ID has already been used or there is a database conflict
410 Gone -- The resource requested has been removed from our servers
423 Locked -- The resource cannot be updated until an unlock operation is performed
425 Too Early -- The resource is unavailable until a pending slower operation is completed elsewhere
429 Too Many Requests -- You're requesting too many resources! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- The Doordeck device is offline. Please try again later.
504 Gateway Timeout -- The Doordeck device didn't response in a timely manner