Sharing Doors
A low level guide to sharing doors and secure operations.
Sharing a door is one of the secure operations within Doordeck that must be performed by a door administrator who has a valid ephemeral key, see our guide on registering an initial ephemeral key and registering subsequent ephemeral keys when logging into new devices.
Although the actual operation to share a door is structurally very similar to an unlock request, there is some initial data needed before we can proceed, in particular we need to know the Doordeck identifier for the user you want to share a door with and we need to know their public key.
Doordeck provides a convenient endpoint for locating the Doordeck identifier and public key of your users – you can query by email, telephone, your own user identifier (foreignKey) or an encrypted OpenID identity which we’ll explore a bit later.
As a reminder, whenever you call any of our endpoints with a valid OpenID token, we’ll dynamically create that user and update our internal user directory with their details, for this example let’s assume that Doordeck knows about the following user.
- Subject: 123
- Email: info@doordeck.com
- Telephone: +442034341020
I can now query the internal directory for the Doordeck identifier and public key of this user through any one of those identifiers.
All of these requests will return the same user:
The user directory endpoint is designed to be called directly by any valid user, so you can avoid proxying the request via your backend, should you choose to.
Now you’ve got the user details, you can generate a sharing request, this looks structurally similar to unlocking a door but the operation object contains an ADD_USER type instead; as we do with other secure operations, let’s start by creating the body of the JWT request:
There are a number of important fields in the request body, you can view the full details on the endpoint details but here is a summary:
As a quick aside, we don’t support all of the OpenID tokens, but we won’t reject any tokens that include extra, this is the full list we support:
| Field | Description |
|---|---|
|
iss |
Your Doordeck identifier
|
|
sub |
Door identifier to be shared
|
|
operation.type |
ADD_USER to indicate a sharing operation
|
|
operation.user |
Doordeck identifier of the user acquired via the user directory operation
|
|
operation.publicKey |
Public key of the user as acquired by the user directory
|
|
operation.role |
USER or ADMIN depending on the level of permission you want the user to have
|
As with any secure operation, you must also specify the issued at, not before and expires at times, but unlike unlock operations which must be done now, you can specify a longer expiry window for sharing requests, up to 14 days – this can be useful if the door is currently offline and you want to queue the request for when the door comes back online.
Now we need to create a JWT header, since we’re signing the request with your ephemeral key we need to make one exactly the same as when following the initial unlock guide.
This example is populated with my user’s certificate chain, yours will be different (remember, you get the certificate chain when you register or renew your ephemeral key).
Now you’ve got a header and request body, base64URL encode them both, concatenate with a period character, calculate the signature with your private ephemeral key, add it onto the end and you should have a valid sharing request! I’ve glossed over these details because they are identical to the process for unlocking a door.
Questions
Q: How do I know which doors can be shared?
A: We have an endpoint which returns a list of shareable locks (i.e. locks for which you are an administrator).
Q: Why can’t I find a user in the directory?
A: User’s only get added to the directory when you’ve marked the communication method as verified, e.g. you need to include the email_verified: true field or the telephone_verified: true field in the OpenID token for that user.
