Master Lock

The Master Lock Plugin allows you to unlock and manage Master Lock Bluetooth® padlocks and lockboxes by integrating with the Master Lock Mobile SDKs.

This guide provides step-by-step instructions to configure the plugin and use its features through the Median JavaScript Bridge.

👍

Developer Demo

Test your setup during development by embedding the Master Lock demo page in your app.

Implementation Guide

Lock Provisioning (Activation, Setup and Access)

The lock setup and activation is handled using the Master Lock Connected Products Web API. For the latest details, always refer to the official API specification.

In general, you will need the following steps in order to provision a lock, retrieve it's information and provision a new access profile for your users.

Step 1 - API Authentication

Use the /authenticate endpoint to retrieve an API token by using your license and password.

Step 2 - Activate a Lock (Optional)

Use the /v2/device/activate endpoint to active a new lock. Skip this step if your locks are already provisioned.

Step 3 - Retrieve Lock Information

Use the /v2/device to obtain the Firmware Version of your lock(s). The Firmware Version is a required parameter to unlock the lock using the SDK.

Step 4 - Create an Access Profile

Use the /v2/device/accessprofile/create to create a new temporary access profile for your users. Please ensure the access profile has the Unlock permission otherwise the user won't be able to unlock the Bluetooth locks.

There are multiple API endpoints to create access profiles. The endpoint above creates a single profile for a single lock, but you can also create an access profile for multiple locks, or multiple access profiles for a single lock.

Note: Access Profile Permissions

Please always validate with the latest permissions outlined in the Master Lock Access Profile and Permissions documentation.

JavaScript Bridge Functions

Plugin Permissions

The Master Lock Plugin requires Bluetooth and Location permissions to scan for and interact with nearby locks. These permissions are requested automatically at runtime.

If you prefer to check and request permissions before initializing the plugin, see our Permissions Overview for implementation details.

Initialize Master Lock SDK

The SDK must be initialized before scanning or unlocking. This design supports multiple Master Lock licenses within the same app.

↔️Median JavaScript Bridge

JavaScript

median.masterlock.initialize({ license })

Scan for Locks

Discover nearby Master Lock devices. You are able to define a scanning timeout in milliseconds (otherwise a default value of 15s will be used) and can are able to define functions for each of the following events:

• onScanStart: App started scanning for nearby locks.
• onScanStop: App stopped scanning for nearby locks.
• onDeviceDiscover: App discovered locks.

↔️Median JavaScript Bridge

JavaScript

median.masterlock.scan({
  onScanStart: "onScanStart",
  onScanStop: "onScanStop",
  onDeviceDiscover: "onDeviceDiscover",
  timeout: timeout,
});

Unlock a Lock

Unlocking requires the Device ID, Access Profile, Firmware Version, and a timeout value (in milliseconds).

↔️Median JavaScript Bridge

JavaScript

median.masterlock.unlock({
  deviceId,
  accessProfile,
  firmwareVersion,
  mechanism: "primary" | "secondary"
  timeout: timeout
});

Parameters:

• deviceId: The lock's unique identifier - available during setup or Master Lock API.
• accessProfile: Profile generated via the Master Lock API.
• firmwareVersion: Lock firmware version.
• mechanism: Defines the primary or secondary lock mechanism.
• timeout: Time in ms before auto-relock.

Testing Your Integration

Hardware Testing

🔧

Test Environment

Hardware-dependent features cannot be tested using simulators. You'll need a physical Master Lock padlock or lockbox.

iOS testing requires a TestFlight or local build using XCode. For Android you can download the APK directly from App Studio.

Please follow the following steps for an end-to-end test

1. Activate and set up a lock using the Master Lock API.
2. Collect the Device ID and Firmware Version using the Master Lock API.
3. Create a new access profile via the API.
4. Switch to your mobile app and initialize the SDK by providing your license key.
5. Use the collected parameters to unlock the test lock.
6. The lock automatically re-locks after the configured timeout.

Frequently Asked Questions

Can I manually relock my padlock or lockbox?

No. Padlocks and lockboxes cannot be manually re-locked via the integration. They automatically lock after a preset timeout.

Why am I receiving a “Not Permitted” error when unlocking?

This error indicates the access profile does not include the required permissions for the lock type. Confirm that the correct permissions (e.g. Unlock, UnlockDoor, or UnlockShackle) are assigned to the access profile.

Full Error Code:

{ 
  "success": false, 
  "error": "Error in response - Not Permitted)
}