LivionKey API V1 API Requirements

At least on LivionKey automat.
- Supported automats: This API is designed for integrating with LivionKey30 and LivionKey1 devices.
- Unsupported automats: This API is not compatible with LivionKey20 devices.
- The first-generation LivionKey app is still required to install and configure the LivionKey automats continue to be used in parallel with this API.
Valid API credentials. Contact our support team to get those.

Latest Version

For the most up-to-date LivionKey API Specification, please visit: https://drive.google.com/file/d/1HYEtOCD0ZCjk_0qohngC99kCR8iE7TOe/view?usp=drive_link

Core Concepts

Devices

Devices represent physical LivionKey Boxes.
Each device has a unique deviceId and contains up to 30 lockers/keys.
API Operations:
- GET /devices: Retrieve all accessible devices.
- GET /devices/{deviceId}: Retrieve a specific device by its deviceId.
- GET /devices/{deviceId}/keys: Retrieve all keys associated with a device.
- GET /devices/{deviceId}/contracts: Retrieve all contracts associated with a device.

Keys

Keys are associated with a specific locker within a device.
Each key has a unique keyId and a customizable customKeyName per device.
A key can be associated with multiple contracts.
Key statuses: 'key-added', 'key-fetched', 'key-returned', 'key-not-returned'.
API Operations:
- POST /keys: Create a new key.
- POST /keys/{keyId}: Update an existing key.
- DELETE /keys/{keyId}: Delete a key.
- GET /key/{keyId}: Retrieve a specific key.
- GET /key/{keyId}/status: Retrieve the status of a specific key.

Contracts

Contracts grant access rights to a specific locker (key).
Each contract has a unique contractId and a contractID (name).
Contracts have start and end dates (or can be permanent).
Contracts for the same key cannot overlap.
Contracts include a pincode for locker access.
API Operations:
- POST /contracts: Create a new contract.
- POST /contracts/{contractId}: Update an existing contract.
- POST /contracts/{contractId}/pincode: Update a contract's pincode.
- DELETE /contracts/{contractId}: Delete a contract.
- GET /contracts/{contractId}: Retrieve a specific contract.

Note: For detailed information on endpoint parameters and responses, please refer to the LivionKey API Specification document.

Authentication

All LivionKey API endpoints require a valid JSON Web Token (JWT) in the request headers. Livion provides authentication via a dedicated REST API endpoint.

A specific endpoint allows for token retrieval, returning the token and its expiration time.
Developers must handle token expiration by storing the expiration time, and requesting a new token before the old one expires.

Basic Scenarios

Contract Creation:
1. GET /devices (select device).
2. GET /devices/{deviceId}/keys (select key).
3. POST /contracts (create contract using deviceId and keyId).
Contract Update:
1. GET /contracts (select contract).
2. POST /contracts/{contractId} (update contract).
Contract Deletion:
1. GET /contracts (select contract).
2. DELETE /contracts/{contractId} (delete contract).
Key Creation:
1. GET /devices (select device).
2. POST /keys (create key using deviceId).

Remember:

Our support team can help you with any questions or integration challenges.
Please take a look at our collection of articles for more detailed instructions and troubleshooting tips.

We hope this article has provided a helpful overview of third-party API integration with LivionKey30. Happy integration!