LivionKey API v2: Mechanical keys and key contracts

LivionKey API v2 provides dedicated endpoints for mechanical keys and mechanical key contracts. Use these endpoints for new integrations. If your integration already uses the devices, keys, and contracts endpoints in API v1, see Legacy LivionKey API v1: Devices, keys, and contracts instead.

API v2 is the recommended version for new integrations. It uses service-account request signing, not the JWT authentication used by API v1.

Before you begin

Make sure that you have:

A LivionKey organization with API v2 enabled.
A service account ID and its private key. The private key is shown only once when the service account is created, so store it securely.
The relevant organization unit or key automat IDs, or a description of the manual storage location, as applicable.
Read the LivionKey API v2 reference for the complete request and response schemas.

Contact Livion Support if you need API access or service-account credentials.

Base URL and authentication

The production base URL is:

https://api.livionkey.com/v2/

Every API v2 request must be sent over HTTPS and signed with your service account. A signed request includes these headers:

x-service-account-id: your service account ID.
x-timestamp: the current timestamp in milliseconds.
x-signature: the signature created with your service account's private key.

Follow the authentication instructions and code examples. Never send your private key to Livion or include it in support requests.

Core concepts

Mechanical keys

A mechanical key has its own ID and can be stored in either:

A LivionKey automat, identified by automatId.
A manual storage location, described with manualStorageInfo.

When creating a key, set away to indicate whether the key is already away from its storage location. Automat keys can also be marked as shared when overlapping contracts are needed; manual-storage keys cannot be shared.

A key response distinguishes three storage states:

selectedStorage: the key's configured home location.
storage: the key's current location.
targetStorage: its destination during a move or return flow.

Mechanical key contracts

A mechanical key contract grants a contact access to one or more keys for a defined period. A contract contains the contact, start and optional end time, keys, storage information, and optional notification and verification settings.

API v2 supports three contract flows:

Default: hand over keys and expect them to be returned.
Fetch only: hand over automat-stored keys without requiring a return.
Return only: receive keys back without a prior handover contract.

Recommended workflow

1. Create or locate the key

Use POST /mechanical/keys to create a key. For example, this request body creates a key stored in an automat:

{   "id": "APARTMENT-A12",   "name": "Apartment A12",   "selectedStorage": { "automatId": "AUTOMAT_ID" },   "shared": false,   "away": false }

For a manually stored key, replace selectedStorage with a manual storage description:

{   "id": "OFFICE-MASTER",   "name": "Office master key",   "selectedStorage": { "manualStorageInfo": "Reception, drawer 2" },   "shared": false,   "away": false }

Use these endpoints to inspect and maintain keys:

GET /mechanical/keys — list keys with pagination and filters.
GET /mechanical/keys/{id} — get one key.
PATCH /mechanical/keys/{id} — update a key.
DELETE /mechanical/keys/{id} — delete a key.

2. Create a key contract

Use POST /mechanical/keycontracts for the normal handover-and-return flow. This example assigns one automat-stored key to a contact:

{   "id": "BOOKING-1042",   "start": "2027-02-16T08:20:00.000Z",   "end": "2027-02-20T08:20:00.000Z",   "contact": {     "name": "John Doe",     "email": "[email protected]",     "phoneNumber": "+358401234567",     "sendSms": true,     "sendEmail": true,     "language": "en"   },   "keys": [{     "id": "APARTMENT-A12",     "storageInfo": { "automatId": "AUTOMAT_ID", "pincode": "654321" }   }],   "freeLockerAfterFetch": false }

The API can generate a PIN code when one is not supplied. See the API reference for current validation rules, contact fields, notification settings, user verification, group-based automat selection, and manual-storage contracts.

3. Read, update, or remove the contract

Use these endpoints throughout the contract lifecycle:

GET /mechanical/keycontracts — list contracts with pagination and filters.
GET /mechanical/keycontracts/{id} — get one contract.
PATCH /mechanical/keycontracts/{id} — update a contract.
DELETE /mechanical/keycontracts/{id} — delete a contract.

When updating contact information, send the complete contact object, not only the individual field that changed. A contract cannot be deleted while one of its keys has been fetched and not yet returned.

One-way contract flows

Use the specialized endpoints only when the physical key flow is one-way:

POST /mechanical/keycontracts/fetch-only — hand over a key without requiring a return. This endpoint supports automat-stored keys only.
POST /mechanical/keycontracts/return-only — accept the return of a key without a prior handover.

The contract response includes a contractType value: 1 for default, 2 for fetch only, and 3 for return only.

Moving from API v1

API v2 is not a field-for-field rename of API v1. Plan migration work for these differences:

API v1 uses a login and bearer token; API v2 signs every request with a service account.
API v1 couples keys to devices and lockers; API v2 models keys separately from their selected, current, and target storage.
API v2 uses different paths, HTTP methods, identifiers, paginated list responses, contact structures, and per-key PIN codes.
API v2 does not expose a direct equivalent of the API v1 contract PIN-code regeneration endpoint. Confirm the intended workflow with Livion Support if your integration depends on regenerating PIN codes.

Keep an existing API v1 integration on the legacy v1 workflow until its migration has been designed and tested.

Important validation and operational notes

Use ISO 8601 date-time values, including a timezone, for start and end.
A contract must contain at least one key.
Automat and manual-storage keys cannot be mixed in one contract.
Key IDs cannot contain spaces. Contract IDs accept letters, numbers, underscores, periods, and hyphens.
If SMS notifications are enabled, provide a valid phone number. If email notifications are enabled, provide a valid email address.
API v2 is rate limited to 1,000 requests per minute per client. If the API returns 429 Too Many Requests, retry with exponential backoff.
Consult the live API reference before implementation because it is the source of truth for fields, validation, responses, and newly added functionality.

Full API reference

Use the LivionKey API v2 reference for complete schemas and examples:

Need help?

Contact Livion Support and include your organization, service account ID, endpoint, HTTP status, approximate time and timezone, and request ID if available. Do not send your private key, signatures, PIN codes, or other credentials.