Access Key Display Help

Overview

The access key modal shows whichever of the three key types are enabled for your facility: QR Code, PIN Code, and/or Remote Unlock Button. Which types appear depends on settings configured by the facility owner:

  • Walk-in (same-day check-in): controlled by enabled_key_types in the Check-in Configuration (checkin_configurations)
  • Advance booking check-in: controlled by enabled_key_types in the Room Plan Mapping (room_plan_mappings) for each plan

The Remote Unlock button appears in all three key modals: check-in complete, key info, and checkout complete.

Features

Feature 1: QR Code Display

If QR code is enabled (enabled_key_types includes "qr"), a QR code is shown at the top of the modal.

  • Hold the QR code up to the facility's reader to enter
  • The QR code grays out when it expires
  • For time-based plans, you can refresh an expired QR automatically or manually

See About QR Code Expiration for details on when keys expire.

Feature 2: PIN Code Display

If PIN code is enabled (enabled_key_types includes "pin"), a 4–10 digit numeric code is displayed in large block format.

Digit Count Display Format
4 digits 2 + 2 (with gap)
6 digits 3 + 3
8 digits 4 + 4
10 digits 5 + 5

Copying the PIN Code

Tap the "Copy" button to copy the PIN to your clipboard. The button turns green with a checkmark to confirm the copy was successful. Copying is disabled when the key has expired.

How to Use the PIN Code

  1. Note the PIN code displayed in the modal
  2. Enter the digits on the door keypad
  3. The door unlocks

Why the PIN Code Might Not Appear

The PIN code may not appear for the following reasons.

  • PIN not enabled in facility settings: The facility owner has not included "pin" in enabled_key_types
  • Walk-in hourly check-in (keyType=1): For walk-in check-ins on time-based (hourly) plans, KEYVOX issues an offline QR code (keyType=1), which does not include a PIN. If you need PIN access, ask the facility owner to review their configuration

Feature 3: Remote Unlock Button

If remote unlock is enabled (enabled_key_types includes "remote_unlock"), a Remote Unlock button appears at the bottom of the modal.

This lets you unlock the door directly from the app without holding your phone up to a reader — just tap the button.

The button appears in all three of the following modals:

  • Check-in complete modal
  • Key info modal (the screen shown when you tap "View Key" during a stay)
  • Checkout complete modal

Button States

State Label Icon
Idle "Unlock" Lock icon (blue)
In progress "Unlocking..." Spinning indicator
Success "Unlock request sent" Green checkmark
Error "Unlock failed" Lock icon (red)
Cooldown "Unlock (Xs)" Lock icon (faded)

The "Unlock request sent" success message means the request has reached the KEYVOX cloud. The door's physical unlocking is processed by KEYVOX.

How to Use Remote Unlock

  1. Tap the "Unlock" button
  2. Wait for "Unlocking..." with the spinner (typically 1–3 seconds)
  3. When "Unlock request sent" appears with a green checkmark, the door is open
  4. After 3 seconds, the button enters a 10-second cooldown automatically
  5. Once the countdown ends, the button becomes active again

About the Cooldown Period

After a successful unlock or an error, a 10-second cooldown prevents accidental or repeated activations. During cooldown, the remaining seconds are shown, for example: "Unlock (9s)".

Facility Owner Configuration

Walk-in key type settings (checkin_configurations)

The key types displayed for walk-in check-ins are controlled by enabled_key_types in the Check-in Configuration screen.

Value Effect
"qr" Show QR code
"pin" Show PIN code
"remote_unlock" Show remote unlock button

Configuration Examples

["qr"]

Default setting (QR code only). Maintains backward compatibility with existing configurations.

["qr", "pin"]

Show both QR code and PIN code.

["qr", "remote_unlock"]

Show QR code and remote unlock button.

["qr", "pin", "remote_unlock"]

Show all three key types.

Advance booking key type settings (room_plan_mappings)

The key types displayed for advance bookings are configured per plan in the Room Plan Mapping. The same enabled_key_types values apply.

Location: Room Management > target room > "Plan Mappings" section > enabled_key_types per plan

Setting up the lock ID for remote unlock

Remote unlock requires both of the following:

  1. KEYVOX account connected: Complete the KEYVOX integration on the Lock Connection page
  2. Unlock lock ID configured: On the Lock Connection page, select which lock to unlock for each KEYVOX unit

The admin selects the target lock ID directly in the Lock Connection page — guests do not need to choose. For setup instructions see Lock Connection.

If no lock ID is configured for a unit, remote unlock returns a "Lock ID not found" error.

Troubleshooting

Q: The PIN code is not showing

Check the following.

  1. Verify facility settings: Ask the facility owner whether "pin" is included in enabled_key_types (check-in config for walk-ins, room plan mapping for bookings)
  2. Check the check-in type: Walk-in check-ins on hourly (time-based) plans use keyType=1 (offline QR), which does not issue a PIN. Accommodation and daily flat plans use keyType=0 and do issue a PIN
  3. Use the QR code instead: Try entering with the QR code if it is displayed

Q: The Remote Unlock button is not showing

The facility owner needs to add "remote_unlock" to enabled_key_types. For walk-ins, this is in the check-in configuration; for bookings, it is in the room plan mapping.

Q: I tapped Remote Unlock but the door did not open

Check the following.

  • Confirm you have a stable internet connection
  • Ask the facility whether the KEYVOX lock hardware is working normally
  • Confirm the unlock lock ID is correctly configured for the unit on the Lock Connection page (facility owner action)
  • Confirm the KEYVOX account integration is active (facility owner action)

Q: "No keys available" is shown

This appears when the connector cannot provide the key types specified in enabled_key_types. Contact the facility owner and ask them to verify that the enabled_key_types setting in the check-in configuration or room plan mapping matches the KEYVOX configuration.

Q: Remote unlock showed an error

Even after an error, a 10-second cooldown applies. Wait for the countdown and try again. If the error repeats, contact the facility.

Q: Both QR code and PIN code are showing — which should I use?

The facility owner has enabled both. Use whichever is more convenient for the door you are trying to open.