Lock Connection Help
Overview
Lock Connection is where you configure integration with smart locks. Once connected, automatic unlocking during check-in becomes possible.
UnlockOS runs on a Lock Adapter layer, so a smart lock that exposes a public cloud API can be connected to it. KEYVOX is built in and you can set it up yourself from this screen. Other providers are enabled through a per-model integration, so contact us with the lock you already have. The steps below cover the KEYVOX tab.
Keypad-style locks whose PIN never changes have no cloud API, so they are registered on the Fixed Code Lock page instead of here (External Integrations → Fixed Code Lock).
Key Features
- Integration with KEYVOX account
- View list of registered lock devices
- Disconnect integration
- Automatic setup of KEYVOX notifications (webhook)
Tabs
| Tab Name | Description |
|---|---|
| KEYVOX | Integration with KEYVOX smart locks |
| Stripe | Integration with Stripe payments |
| LINE | Integration with LINE Official Account |
Stripe Payment Tab
The Stripe tab lets you connect a Stripe account to enable online payments. After connecting, you can charge guests for pre-payment, post-payment, and deposits during check-in.
KEYVOX Integration
Connection Status
| Status | Description |
|---|---|
| Connected | Successfully connected to KEYVOX account |
| Disconnected | No connection to KEYVOX account |
Buttons
| Button | Description |
|---|---|
| Login with KEYVOX | Perform OAuth authentication with KEYVOX account |
| Logout | Disconnect from KEYVOX |
Webhook (entry and exit events)
This setting receives notifications from KEYVOX when a lock opens, closes or fails to open, and when something is deposited in a locker. These notifications update details such as the usage status on a reservation. It appears in the lower half of the connection status card.
When you connect KEYVOX, UnlockOS registers it with KEYVOX automatically. As with the webhook on the Stripe payment settings, you can press "Set up automatically" to run it again at any time. The setting is shared by every facility in the organization.
This section is being rolled out gradually. If you don't see it, keep setting up webhooks per lock in the BACS console as before.
| Status | Meaning | What to do |
|---|---|---|
| Configured | Registered with KEYVOX | Nothing |
| Not configured | Nothing is registered with KEYVOX yet | Press "Set up automatically" |
| Needs an update | Registered, but some events are missing | Press "Set up automatically" (it registers again) |
| Waiting for the new signing key | After the signing key was updated, the new key has not reached this KEYVOX account yet | Press "Set up automatically". The old key is still accepted for 7 days |
| Used by another UnlockOS organization | Another UnlockOS organization uses the same KEYVOX account | One KEYVOX account cannot be used by more than one organization. Remove the registration from that organization's facility, then press "Set up automatically" here |
| Registered to another destination | A destination outside UnlockOS is registered for this KEYVOX account | Check with whoever uses it, delete it in the KEYVOX console, then press "Set up automatically" |
| Could not check | UnlockOS could not reach KEYVOX. The reason is shown next to it | While it says "KEYVOX is not accepting automatic webhook setup right now.", webhooks set up per lock in the BACS console keep arriving as before |
| Button | Description |
|---|---|
| Set up automatically | Registers with KEYVOX. Facility owners and above can use it |
| Update signing key | Creates a new signing key and updates the KEYVOX registration without interrupting delivery. It applies to every facility in the organization, and the old key is still accepted for 7 days. Shown only to organization owners |
| Remove registration | Deletes the UnlockOS registration from KEYVOX. After that, entries, exits and locker deposits are no longer recorded. If another facility uses the same KEYVOX account, the KEYVOX registration stays and only this facility's record is removed |
The signing key is never shown. UnlockOS passes it to KEYVOX directly.
If you set up webhooks per lock in the BACS console, delete those settings once this shows "Configured". Otherwise the same notification arrives twice.
Device List
Places
Registered locks are displayed grouped by location.
Doors
Under each place, registered doors and lock units are displayed.
Display Fields
| Field | Description |
|---|---|
| Place Name | Name of the location where the lock is installed |
| Door Name | Name of the door |
| Unit Name | Name of the lock unit |
| Unit ID | KEYVOX unit identifier (click to copy) |
| Unlock Lock | The lock ID used for remote unlock (selected by the admin) |
Operations
Connecting with KEYVOX
- Click the "Login with KEYVOX" button
- You will be redirected to KEYVOX login page
- Log in with your KEYVOX account
- After authentication, you will automatically return to UnlockOS
- Registered lock devices will be displayed in a list
Copying Unit ID
Click on a Unit ID to copy it to clipboard. This is used in check-in configuration.
Setting the Unlock Lock ID (required for remote unlock)
To allow guests to use the Remote Unlock button, you must assign an unlock lock to each unit.
- Expand the unit in the device list
- Select the lock ID from the "Unlock Lock" dropdown for that unit
- The setting is saved automatically after selection (a ✓ indicator appears)
If a KEYVOX unit has multiple lock IDs associated with it, all candidates appear in the dropdown. Select the lock corresponding to the door the guest should unlock.
If no unlock lock ID is configured, guests who tap the Remote Unlock button will see a "Lock ID not found" error.
Disconnecting
- Click the "Logout" button
- Select "Yes" in the confirmation dialog
- KEYVOX integration will be disconnected
FAQ
Q: What should I do if KEYVOX connection is lost?
A: Click the "Login with KEYVOX" button again to reconnect.
Q: Can I use KEYVOX with multiple facilities?
A: Yes, you can connect KEYVOX accounts for each facility.
Q: What if locks are not displayed?
A: Please verify that the locks are properly registered in the KEYVOX dashboard.
Q: How do I specify locks in check-in configuration?
A: Copy the Unit ID from the list on this page and paste it into the check-in configuration screen.
Q: The Unlock Lock dropdown is not showing for a unit
A: The dropdown only appears when the KEYVOX unit has at least one lock ID associated with it. Check the KEYVOX dashboard to confirm that a lock is correctly assigned to the unit.
Related Pages
- Check-in Configuration
- Check-in List
- Base Settings
- LINE Integration
- Fixed Code Lock
- Access Key Display (QR, PIN & Remote Unlock)
- Notification Workflow Help