Retrieving Access

Status: Planned (v4). The endpoints on this page describe the v4 access API that is being built. The shapes below are the intended contract. Until they ship, confirm provisioning by polling event status; ask your Mosler contact for the current retrieval method.

Once a booking event reaches COMPLETED, Mosler has provisioned the guest's credential. This page is the pull half of the loop — the API your system calls to read that credential. (To have Mosler push it to you or the guest instead, see Delivering Access.)

All endpoints authenticate with your company-scoped API key in the apikey header and are looked up by the booking's referenceId.

---

Credential types at a glance

---

List a booking's credentials

Returns all active credentials for a booking in a human-readable form.

GET /api/v4/bookings/:referenceId/access

Response

Each access[] entry:

E-key: when type is ekey, this endpoint confirms the key exists but does not return the lock data. Call GET …/access/e-key to get the data your app needs to operate the lock.

Example — passcode booking

{
    "success": true,
    "booking": {
        "id": "6576fe78632cfff91c62a3c2",
        "referenceId": "RES-20250718-001",
        "status": "active",
        "startDate": "2025-08-01T08:30:00.000Z",
        "endDate": "2025-08-05T05:30:00.000Z"
    },
    "access": [
        {
            "deviceId": "63f79d8b8c0d1a55c3172f3c",
            "deviceName": "Room 101 Door",
            "roomNumber": "101",
            "bedNumber": null,
            "siteName": "Delhi",
            "validFrom": "2025-08-01T08:30:00.000Z",
            "validUntil": "2025-08-05T05:30:00.000Z",
            "type": "passcode",
            "passcode": "482910"
        }
    ]
}

Example — multiple locks (door + cabinet)

{
    "success": true,
    "booking": { "referenceId": "RES-20250718-002", "status": "active" },
    "access": [
        {
            "deviceName": "Room 101 Door",
            "roomNumber": "101",
            "bedNumber": null,
            "type": "passcode",
            "passcode": "482910"
        },
        {
            "deviceName": "Bed A Cabinet",
            "roomNumber": null,
            "bedNumber": "A",
            "type": "passcode",
            "passcode": "391047"
        }
    ]
}

---

Get e-key lock data

Returns the data a mobile app needs to operate an e-key (Bluetooth) for the booking. Pass lockData to the Mosler mobile SDK as-is — it is opaque to your app. The lock manufacturer is abstracted by Mosler; your integration does not need to know which vendor a given lock uses.

GET /api/v4/bookings/:referenceId/access/e-key

v3 → v4 difference: In v3 the equivalent endpoint was GET /api/v3/booking/access/ekey/:bookingId, keyed by the internal bookingId. v4 keys by referenceId (the string you sent when creating the booking), wraps results per-device in a standard envelope, and adds lockMac alongside lockData. The field names lockData and lockMac are the same as v3.

Response

data contains one entry per lock the booking has an e-key on:

{
    "error": false,
    "code": 7005,
    "message": "E-keys retrieved successfully",
    "data": [
        {
            "lockData": "Rz7oNSAH1No3YXRiG0j8FKB3xBjhuILrkTjWkOMw...",
            "lockMac": "AA:BB:CC:DD:EE:FF",
            "deviceId": "63f79d8b8c0d1a55c3172f3c",
            "deviceName": "Room 101 Door",
            "locationType": "door",
            "roomNumber": "101",
            "bedNumber": null,
            "siteName": "Delhi",
            "validFrom": "2025-08-01T08:30:00.000Z",
            "validUntil": "2025-08-05T05:30:00.000Z"
        }
    ]
}

Pass lockData and lockMac to the Mosler mobile SDK when initialising the lock for a Bluetooth operation. Both values are required for SDK initialisation — store them like credentials.

---

Remote unlock

Triggers a server-side unlock on a lock for an active booking — no guest credential required. Designed for staff and kiosk flows: a front-desk attendant clicks a button and the door opens.

POST /api/v4/bookings/:referenceId/unlock

Request body

Validation

• Booking must exist and be active.
• Current time must fall within the booking's check-in → check-out window.
• A device must be bound to the booking's room (or bed).

Response

{
    "message": "Remote unlock successful",
    "error": false,
    "data": {
        "deviceId": "63f79d8b8c0d1a55c3172f3c",
        "deviceName": "Room 101 Door",
        "unlockTime": "2025-08-02T11:04:33.000Z"
    }
}

Every attempt — success or failure — is written to the device's access log, visible in the Mosler Admin Portal under Devices → Access Logs.

---

Error responses