Guides and Articles

Access Management & Door Locks

Suggest Edits

This UI supports 3 types of keys: Keycards, Access Codes, and Mobile Keys. The UI remains consistent with small differences for each type of key. The UI is currently in limited release, so please reach out to [email protected] to enable this for your demo and pilot properties.

UI Overview
The reservation view has a key icon.

  1. If keys are issued, then clicking on the key icon will open the dialog that shows the keys, their details.
    a. For Access codes, the code is displayed here
    b. For Mobile Keys, the URL for the key download is here

  1. If keys have not been issued, then this same link will first open to the Issue keys Modal.

a. This creates a key record and sends the webhook to create keys and awaits an update to the key record to confirm the key has been issued.

API Links
Key API https://developers.cloudbeds.com/v1.2/reference/doorlockkeycontrollercreate
Cloudbeds API https://developers.cloudbeds.com/v1.2/reference/about-pms-api

Door Lock feature certification mandatory requirements.(*)
Use at least one of the 2 following flows: Keycards and/or Access codes/Mobile Keys. This will depend on the door lock providers that you support e.g. Salto via Access codes and Dormakaba via Keycards to be used according to customer preference.

Integration Steps for Keycards
Physical keycards require interaction between the UI and the door lock system. The steps below outline how the middleware between the Cloudbeds API and a door lock system would work.

  1. Set up Key settings to add system settings such as Encoder IDs.
  2. Subscribe to the doorLockKey/key_requested webhook.
  3. When the user clicks issue key,
    a. A keycard record is created on Cloudbeds in Processing status
    b. The `doorLockKey/key_requested`` webhook. is sent, use the data from this webhook to perform the following actions
    1. Use the key ID from the webhook with the keys endpoint to request additional key information
    2. Use getReservation call to get any additional reservation or guest information needed to create keys.
    3. Send the issue key request to the doorlock software
      1. At this point, the user will place the key on the keycard encoder
        c. Once the key has been created, update the key record as completed; this will trigger the UI to continue on to the next step. Use the /keys/:id endpoint to update the key record
    4. If an error occurs, update the key record with the status to failed and set the errorMessage to the message you would like displayed to the user.

Actions that will also need to be handled by the integration.

  1. Multiple Key Creation
    a. For each requested key, you will receive a single webhook..
    b. These will come in one at a time as keys are issued.
  2. Handle Key Invalidation
    a. A webhook is issued to invalidate the key (doorLockKey/key_cancelled)
  3. Handle Room Reassignment
    a. Subscribe to the reservation/accommodation_changed
    b. Use old_room to invalidate the old code and roomID to create new keys for the new room

NOTE: In addition, most keycard systems are on on-prem installs, so solutions will need to include a way to get into the hotel network to communicate with the door lock system. Cloudbeds has a bridge app to achieve this. We are willing to share the source code for this application if you would like to use this for your solution. The steps above do not include this additional

Explore Cloudbeds Salto Integration to see this in action.

Integration Steps for Access Codes and Mobile Keys
We suggest using the room assignment webhook to generate keycodes and mobile keys. Room assignment can happen anytime before a guest checks in, but generally happens the night before or day of check-in. This process will create the key record, which can then be communicated to the guest via email, sms, or upon arrival at the hotel.

  1. Set up Key settings
  2. Subscribe to the reservation/accommodation_changed webhook.
  3. When receiving this webhook, do the following steps.
    a. Use getReservation call to get any additional reservation or guest information needed to create keys
    b. If an old_roomID is passed in the webhook, invalidate any previously generated keys for the old room.
    c. Generate the access code or mobile key
    d. Create a new key record with the created key using the Keys Endpoint
    e. This newly generated key can then be shared with the guest.

Actions that will also need to be handled by the integration.

  1. Handle Key Creation
    a. If the “Issue Keys” button is clicked, a key record is created, and a webhook is sent to the integration. The integration should create an additional access code and write it back to the key record. This flow is similar to the steps to Issue Keycard
    b. The UI awaits an update on the key record to confirm that the key was created.
  2. Handle Key Invalidation
    a. A webhook is issued to invalidate the key.
  3. Handle Room Reassignment
    c. Subscribe to the room assigned webhook
    d. Use old_room to invalidate the old code and roomID to create new keys for the new room

Key Settings Configuration
There are a few settings each property needs to set up to be able to issue keys. You will need to gather this information from the customer and sync it to Cloudbeds. The doorlock's setting API endpoints can be used to set these settings.

  1. Encoders ( keycards only ): This is used to select encoders. It consists of pairs of ID and display name for each encoder. When the user selects an encoder, the ID for this encoder is sent in the keycard request.
  2. keyTypes: the list of keytypes your integration selects allowed values (key_card, access_code, mobile_key)
  3. commonRooms: a list of common rooms. It consists of pairs of ID and display name for each common room. When the user selects an encoder, the ID for this common room is sent in the keycard request.

Mapping Rooms
Often, the names of rooms in the Cloudbeds system do not match the names or room IDs of the door lock in the door lock system. Cloudbeds has provided a way to include this mapping in the room definition.
The Doorlock IDs can be set in the Cloudbeds room definition UI (see below) and retrieved using the getRooms endpoint, which returns the doorlock.

  1. Navigate to Settings->Property->Accommodations tab.
  2. Select an Accommodation Type, and scroll down to the Room Name
  3. Click Edit next to the room name you would like to edit, and add the ID or name to the Doorlock ID column

Edge Cases to keep in mind

  1. Multiple rooms on a single reservation.
    a. These are represented as subreservations, each subreservation represents a single room.
  2. Multiple guests on the reservation
    a. You can choose to create multiple keys for this case or create a unique key for each guest.
  3. Split reservations
    a. In this scenario, you will find the same 'subReservationID' assigned to multiple rooms for non-matching stay periods.
    b. You need to make sure that the key is assigned to the relevant room for the correct stay dates.

Updated 7 days ago