Batch Share A Lock (v2)

info

Not all devices support this operation, check for the presence of the BATCH_SHARING_25 capability.

Share a single lock with up to 25 users in a single request.

HTTP Request

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

Success

If a request expires within the next 60 seconds, a 204 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 BATCH_ADD_USER
users	true	List of user objects

The user object definition is as follows

Parameter	Required	Description
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

After the request has been signed with user's private key, it should be sent to the execute endpoint.

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)" \
  --arg publicKey "INVITEE_PUBLIC_KEY" \
  --arg user "11111111-1111-1111-1111-111111111111" \
  --arg role "USER" \
  --argjson nbf "$(date +%s)" \
  --argjson iat "$(date +%s)" \
  --argjson exp "$(($(date +%s) + 60))" \
  --argjson start "$USER_START_TIME" \
  --argjson end "$USER_END_TIME" \
  '{
    iss: $iss,
    sub: $sub,
    jti: $jti,
    nbf: $nbf,
    iat: $iat,
    exp: $exp,
    operation: {
      type: "BATCH_ADD_USER",
      users: [
        {
          publicKey: $publicKey,
          user: $user,
          role: $role,
          start: $start,
          end: $end
        }
      ]
    }
  }'
)

# 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.
• Replace 11111111-1111-1111-1111-111111111111 with the invitee's user ID.
• Replace INVITEE_PUBLIC_KEY with the invitee's public key (retrieve from the lookup user public key endpoint).
• Replace USER_START_TIME and USER_END_TIME with Unix timestamps of when the user should be activated from and until, use null for indefinite.

Response

JSON

{}