Update Secure Settings

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

Success

If a request expires within the next 60 seconds, a 200 is returned upon success, if a request expires in more than 60 seconds, a 202 is returned to indicate the request has been queued for the device.

Request Parameters

The JWT header is formed of the following fields:

Parameter	Required	Description
alg	true	EdDSA EdDSA for ephemeral key signatures
x5c	true	User's certificate chain
typ	true	JWT, JSON Web Token

The JWT 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, set to the current time
iat	true	Issued at, the current Unix timestamp
exp	true	Expires, a Unix timestamp indicating when the request should expire, typically now plus 60 seconds
jti	false (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 operation to perform, see below

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

Example

Request

CURL

# If you don't have an ephemeral key yet, generate one, otherwise reuse the existing one
openssl genpkey -algorithm ed25519 -out private.der

# Format the public key for use with the ephemeral key registration endpoint
PUBLIC_KEY=`openssl pkey -in private.key -pubout -outform DER -out - | base64`

# Register the keypair with Sentry Interactive (may require verification, see "Register Ephemeral Key With Secondary Authentication")
API_RESPONSE=$(curl -s -X POST https://api.doordeck.com/auth/certificate \
  -H 'authorization: Bearer TOKEN' \
  -H 'content-type: application/json' \
  -d '{"ephemeralKey":"'$PUBLIC_KEY'"}')

# Setup variables needed for the unlock operation
CERTIFICATE_CHAIN=$(echo $API_RESPONSE | jq -r .certificateChain)
USER_ID=$(echo $API_RESPONSE | jq -r .userId)
DEVICE_ID="00000000-0000-0000-0000-000000000000" # Replace with the lock's ID

HEADER=$(jq -n \
  --arg alg "EdDSA" \
  --arg typ "JWT" \
  --argjson x5c "$CERTIFICATE_CHAIN" \
  '{
    alg: $alg,
    typ: $typ,
    x5c: $x5c
  }')


BODY=$(
jq -n \
  --arg iss "$USER_ID" \
  --arg sub "$DEVICE_ID" \
  --arg jti "$(uuidgen)" \
  --argjson nbf "$(date +%s)" \
  --argjson iat "$(date +%s)" \
  --argjson exp "$(($(date +%s) + 60))" \
  '{
    iss: $iss,
    sub: $sub,
    jti: $jti,
    nbf: $nbf,
    iat: $iat,
    exp: $exp,
    operation: {
      type: "MUTATE_SETTING",
      unlockDuration: 10
    }
  }'
)


# Prepare and sign the JWT
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'`
echo -n $HEADER_B64.$BODY_B64 > tbs.bin
SIGNATURE_B64=$(openssl pkeyutl -sign -inkey private.key -rawin -in tbs.bin | base64 | sed 's/+/-/g;s/\//_/g;s/=//g')
JWT=$HEADER_B64.$BODY_B64.$SIGNATURE_B64

curl "https://api.doordeck.com/device/$DEVICE_ID/execute"
  -X POST
  -H 'authorization: Bearer TOKEN'
  -H 'content-type: application/jwt'
  --data-binary "$JWT"

Remember

• Replace TOKEN with your access token.
• Replace 00000000-0000-0000-0000-000000000000 with the lock's ID.

Response

JSON

{}