canonical: https://jentic.com/apis/keyvox.co/keyvox

# KEYVOX API

Jentic publishes the only available OpenAPI specification for KEYVOX API, keeping it validated and agent-ready. The KEYVOX API is the integration surface for KEYVOX's smart-lock and smart-locker platform, used by accommodations, rental spaces, and coworking facilities to issue time-limited PIN access tied to a reservation. The seven endpoints split into Smart Lock operations (list units, create a one-time lock pin, unlock a unit, read recent lock events), Smart Locker operations (list lockers, create a locker pin), and Booking operations (read booking orders). Authentication is an HMAC signature passed in the Authorization header, and the base URL is https://eco.blockchainlock.io/api/eagle-pms.

## For AI agents

List smart-lock units and lockers, issue time-limited PIN access tied to bookings, trigger remote unlocks, and read recent lock events through 7 HMAC-signed KEYVOX endpoints.

## Scope

Does not handle reservation creation, payment processing, or property listing - use for KEYVOX smart-lock and smart-locker access control tied to existing bookings only.

## Capabilities

- List the smart-lock units registered to the authenticated property
- Issue a time-limited lock PIN tied to a booking for guest access
- Trigger a remote unlock on a specific KEYVOX smart lock
- Read recent lock events for one or more units to audit access
- List the smart lockers and issue locker PINs for parcel or item handover
- Read the booking orders that drive access-grant decisions

## Use cases

### Self Check-In for Short Lets

Generate a time-limited lock PIN when a short-let booking is confirmed, valid only for the booking's check-in window, and send the PIN to the guest. The `/v1/createLockPin` endpoint accepts the booking parameters; `/v1/getBookingOrders` surfaces the booking that triggered the request. Pair the two with a messaging API and self check-in works end to end without a key handover.

Example prompt: POST `/v1/createLockPin` with the booking_id and check-in window to create a time-bounded PIN, then deliver the PIN to the guest

### Coworking Space Locker Allocation

Allocate a smart locker to a coworking member or visitor by listing available lockers via `/v1/getLockers` and issuing a PIN with `/v1/createLockerPin.` The PIN is scoped to the locker and expires after use, so allocation is automatic and lockers free up cleanly. Most coworking platforms ship this in a couple of days.

Example prompt: GET `/v1/getLockers` to find a free locker, then POST `/v1/createLockerPin` with the chosen locker_id and the recipient details

### Access Audit Across Properties

Audit who accessed which unit by polling `/v1/locks/events` for each unit on a schedule and writing the events to a downstream log store. Combined with the booking orders endpoint, the audit links each unlock to the booking that authorised it, which is critical for dispute resolution and security reviews.

Example prompt: POST `/v1/locks/events` with the unit IDs to fetch, then store the events alongside the matching record from `/v1/getBookingOrders`

### AI Agent Stay Concierge

An AI agent that supports guests during a stay uses Jentic to call KEYVOX at the right moment - issuing a PIN ahead of arrival, triggering an emergency unlock if a verified guest is locked out, or reading recent events to confirm access worked. Jentic injects the HMAC signature per call so the agent never holds the signing key.

Example prompt: Through Jentic, search for 'create a keyvox lock pin', load POST `/v1/createLockPin`, and execute it with the guest's booking_id

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/getUnits` | List smart-lock units |
| POST | `/v1/createLockPin` | Create a time-limited lock PIN |
| POST | `/v1/unlock` | Trigger a remote unlock |
| POST | `/v1/locks/events` | Read recent lock events |
| POST | `/v1/getLockers` | List smart lockers |
| POST | `/v1/createLockerPin` | Create a smart-locker PIN |
| POST | `/v1/getBookingOrders` | Read booking orders |

## Key resources

- **Smart Lock** — List units, issue lock PINs, trigger unlocks, and read lock events
- **Smart Locker** — List lockers and issue locker PINs for parcel or item handover
- **Booking** — Read the booking orders that authorise access grants

## Why Jentic

- **Setup:** Wiring the KEYVOX API by hand means computing its HMAC signature for every request, calling eco.blockchainlock.io/api/eagle-pms, and mapping lock, locker, and booking actions to their POST shapes yourself. Through Jentic you install once, import the KEYVOX API from the API Directory, store the signing key once, and your agent calls it.
- **Permission scoping:** KEYVOX carries its targets in the POST request body rather than a resource id in the URL path, so limit the agent to the operations it needs, such as getUnits and getBookingOrders. You choose that set, so an action like unlock or createLockPin is not included unless you add it.
- **Credential handling:** Your KEYVOX HMAC signing key is stored once, encrypted, by your own Jentic One instance and injected at execution time. Jentic computes the signature per request, so the agent never holds the key or sees the signed payload.
- **Discovery method:** Agents search Jentic by intent such as 'create a KEYVOX lock pin' or 'unlock a KEYVOX lock', and Jentic returns the matching KEYVOX operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **KeyNest** — KeyNest exchanges physical keys at partner stores rather than issuing digital PINs.
- **KleverKey** — KleverKey is another smart-lock platform aimed at short-let and rental access management.
- **Twilio** — Twilio sends the SMS that delivers the smart-lock PIN to the guest.

## FAQ

### Why is there no official OpenAPI spec for KEYVOX API?

KEYVOX does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call KEYVOX API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the KEYVOX API use?

An HMAC signature passed in the authorization header. The signing key is issued from the KEYVOX partner console and signs each request payload. Through Jentic, the signing key is held in the encrypted vault and the signature is computed per call so the raw key never enters the agent's context.

### Can I issue a time-limited PIN with the KEYVOX API?

Yes. POST `/v1/createLockPin` with the unit identifier and the booking window returns a PIN that is valid only for that window. The same pattern applies to lockers via POST `/v1/createLockerPin`, where the PIN is scoped to the chosen locker.

### What are the rate limits for the KEYVOX API?

The OpenAPI spec does not publish a rate limit. With seven endpoints and request volumes typically driven by booking events, throughput rarely hits a hard limit. If you receive HTTP 429, back off exponentially and retry the PIN-creation call.

### How do I trigger a remote unlock through Jentic?

Search Jentic for 'unlock a keyvox lock' to find POST `/v1/unlock`, load its schema, and execute it with the unit identifier and booking context. The Jentic flow is pip install jentic, then client.search, client.load, and client.execute. Jentic injects the HMAC signature for you.

### Can I read recent lock events with the KEYVOX API?

Yes. POST `/v1/locks/events` returns recent events for the supplied unit identifiers, which you can pair with `/v1/getBookingOrders` to link each unlock to the booking that authorised it. This is the data set used for access auditing.

### Can I limit what my agent is allowed to do with the KEYVOX API?

Yes. Because you run Jentic One yourself, you decide which KEYVOX operations your agent may call and which credential it signs with, so you can grant read-only actions like getUnits and getBookingOrders while withholding the rest. KEYVOX carries its targets in the POST request body rather than in the URL path, so a write action such as unlock, createLockPin, or createLockerPin is only available to the agent if you add it to that set. Your HMAC signing key is stored once by your own instance and applied per request, so the agent never handles the raw key while working inside the boundaries you set.