Legacy API: Use this guide only for an existing LivionKey API v1 integration. For new integrations, use LivionKey API v2: Mechanical keys and key contracts. API v1 and v2 use different authentication, endpoints, and resource models, so migration requires implementation changes.

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.

Keypad access rights

Access rights give a PIN code for LivionKey keypads. They are managed with the /accessrights endpoints.
If your organization manages keypad access in LivionKey Register, existing access rights have been migrated to access grants. A migrated access right can no longer be changed through API v1: POST /accessrights/{id}, POST /accessrights/{id}/pincode, and DELETE /accessrights/{id} return 400 with the message "AccessRight has been migrated to KeyRegister and can no longer be modified through API v1".
GET /accessrights/{id} still returns a migrated access right, based on the access grant that replaced it. If that access grant has been revoked, the response is 400 with the message "AccessRight not found".
Manage migrated access in LivionKey Register or with the /access-grants endpoints of LivionKey API v2.

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.

Errors and rate limits

Reuse the token. A token from POST /auth/login is valid for one hour, and the response includes its expirationTime. Log in once, use the same token for all requests, and log in again only shortly before it expires. Don't log in before every request.
429 Too Many Requests on login. Logins are rate limited. When the limit is reached, POST /auth/login returns 429 with the message "Too many login attempts, try again later" and a Retry-After header that gives the wait time in seconds. Wait at least that long before you log in again. Don't retry at once, and don't switch to other credentials: the limit is shared, so other credentials don't help.
401 Unauthorized. The token was rejected, for example because it has expired. Log in again to get a new token and retry the request once. If you still get 401, the account may not have access to the requested resource.
403 "No token provided." The request has no Authorization: Bearer <token> header.
400 on login. The email address or password is missing or wrong. Check the credentials before you try again.

For code examples, see the API v1 developer reference.

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).

To build and test your integration without real hardware, see Testing your LivionKey API integration.

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!

Legacy LivionKey API v1: Devices, keys, and contracts.