Property and building access control to distribute keys for visitors and guests.
Supports different key types like key cards, pin codes and more to come.
Supports multiple hardware vendors.
How to get started:
Create an "Access Control Provider" configuration with the Configuration API. A provider reflects the upstream service provided by the hardware manufacturer.
Create a "Controller" configuration for key distribution, also on the Configuration API. A controller acts as a physical or logical device used to issue keys, such as a card encoder.
Create a key (createKey).
Issue a key card, pin code or any other supported key type.
Servers: http://localhost:8081/api/v2
Extensions to the base API. These extensions are intended for internal use, may change and are not officially supported.
GET /access/providers/{configurationId}/capabilities
Returns the capabilities the configured AccessControl provider supports and the subset invokable as extensions. The set is derived from the configured provider; callers use it to decide which actions to surface without hard-coding provider knowledge.
configurationId (path, string, required) Uuid of the AccessControl provider configuration
200OK
404Provider configuration not found.
GET /access/providers/{configurationId}/extensions/{extensionName}
Generic dispatcher for a provider extension. The response is the provider's native shape, returned verbatim. Returns 404 when the extension is not registered or the configured provider does not support it.
configurationId (path, string, required) Uuid of the AccessControl provider configuration
extensionName (path, string, required) Name of the extension to invoke (e.g. unit-list, unit-sync,
encoder-list). The supported set is owned by the configured provider —
see the capabilities endpoint.
200OK — provider-specific extension payload.
404Extension not registered, provider not found, or not supported by the provider.
502The upstream access-control system could not carry out the request.
The request itself was well-formed and accepted — this is the locking system, its gateway or its
vendor API failing, being unreachable, or refusing because it is busy. errorCode says which.
Retrying is usually worthwhile, but not immediately: a gateway that answered "busy" is still busy a
second later. Where outcomeUnknown is true the write may have landed despite the failure, so
re-run the idempotent form of the operation rather than assuming nothing happened.
Card Dispensers are devices used to dispense keycards or other access media. They can be used to issue keycards to guests or staff members.
GET /access/dispensers/{dispenserId}/status
dispenserId (path, string (uuid), required) Uuid of the card dispenser
200Dispenser status
404The requested resource could not be found.
500An unexpected error occurred on the server.
PUT /access/dispensers/{dispenserId}/status/{state}
Set a state on a card dispenser.
dispenserId (path, string (uuid), required) Uuid of the card dispenser
state (path, CardDispenserState, required) 204No Content
PUT /access/dispensers/{dispenserId}/place-card/{cardPosition}
Place the card on the card dispenser to the designated position.
dispenserId (path, string (uuid), required) Uuid of the card dispenser
cardPosition (path, PlaceCard, required) 204No Content
POST /access/dispensers/{dispenserId}/reset-cache
Drops the service's cached handle for one card dispenser, so the next call to it reconnects and re-reads its configuration. Use after changing a dispenser configuration, or to recover a dispenser the service still believes is in a state it has since left.
Answers 404 when the dispenser holds no cache entry — nothing was reset, which is
not the same as the dispenser being unknown.
dispenserId (path, string (uuid), required) Uuid of the card dispenser
200Cache entry dropped
404The dispenser held no cache entry
POST /access/dispensers/reset-all-cache
Drops every cached dispenser handle at once. The message reports how many entries were cleared; clearing none is a success, not an error.
200Cache entries dropped
Creating keys (keycards, pin codes, etc.) for access control systems.
After creating a key its information are hold in the system. Before a key can be created one needs to setup a provider and a controller first. Controllers define the keyType (such as keycard or pin code) and the provider defines the keyProvider (such as Tesa or Salto).
Some keys such as keycards can only be created if a medium is present (like a keycard encoder), and often times that is also true if you want to delete it.
GET /access/controllers/{controllerId}/key
Reads key of specified controller including data read from keycard.
Intended to be used for physical keycards.
controllerId (path, string (uuid), required) Uuid of the controller
200OK
404The requested resource could not be found.
500An unexpected error occurred on the server.
502The upstream access-control system could not carry out the request.
The request itself was well-formed and accepted — this is the locking system, its gateway or its
vendor API failing, being unreachable, or refusing because it is busy. errorCode says which.
Retrying is usually worthwhile, but not immediately: a gateway that answered "busy" is still busy a
second later. Where outcomeUnknown is true the write may have landed despite the failure, so
re-run the idempotent form of the operation rather than assuming nothing happened.
POST /access/controllers/{controllerId}/key
Creates a new key on the controller. A key can be a keycard, pin code or other key type according to the controller. Note that the response contains some additional information about the key such as a keycard uuid or a pin code number.
unitName is required for any key that reaches the locking system. The unit is
what names the lock, so a key without one has nothing to be written to and is
rejected with 422. The single exception is a key held virtually (see below), where
the unit is expected to arrive before the pin is written.
externalId is required for a key that will be held virtually. On a controller
configured with virtualBefore, a key whose start lies further out than the window
is not written to the locking system yet. Such a key is materialised only through
replaceKeyByReservation, which resolves it by the stay's external id — so without
one the guest would be handed a pin that nothing could ever activate. Creating it is
refused with 400.
This applies only while the key would be held for its start date. Once the window has opened the key goes to the locking system on this call, and no external id is needed to get it there.
controllerId (path, string (uuid), required) Uuid of the controller
application/vnd.api+json · KeyTypes
unitName (string, required) – name of the lock or doororiginal (boolean, required) – create and replace key if true, copy otherwisestartDate (string (date), required) – Date after which the key is validstartTime (string (time)) – Time after which the key is valid, seconds must be 00endDate (string (date), required) – Date after which the key is invalidendTime (string (time)) – Time after which the key is invalid, seconds must be 00authorizations (string[]) – Add/assign authorization to system defaultdeAuthorizations (string[]) – Remove/deny authorization zone from system defaultextraUnits (string[]) – Additional units to grant access totype (string enum, required)providerId (string (uuid), required) – The provider configuration the key was created with.id (string (uuid), required) – The generated UUIDcreatedAt (string (date-time), required) – Time of creationupdatedAt (string (date-time), required) – Time of last updatekeyType (string, required) – The type of the key201Created
400The server could not understand the request due to invalid syntax.
422The request body failed validation.
500An unexpected error occurred on the server.
502The upstream access-control system could not carry out the request.
The request itself was well-formed and accepted — this is the locking system, its gateway or its
vendor API failing, being unreachable, or refusing because it is busy. errorCode says which.
Retrying is usually worthwhile, but not immediately: a gateway that answered "busy" is still busy a
second later. Where outcomeUnknown is true the write may have landed despite the failure, so
re-run the idempotent form of the operation rather than assuming nothing happened.
DELETE /access/controllers/{controllerId}/key
Deletes a key on a "Controller". Typically used for deleting a key-card on a card encoder.
Also consider invalidating a key with deleteKey or replaceKey.
controllerId (path, string (uuid), required) Uuid of the controller
204OK
POST /access/controllers/{controllerId}/keys
Creates several keys of the same kind on the controller in one call — typically a run
of key cards encoded back to back from a dispenser. The key itself is described
exactly as for createKey; quantity says how many to produce.
Encoding is sequential and stops at the first card that fails, so a batch can end
partially done: succeeded reports how many keys were actually created and error
describes the card that stopped the run. Read keys rather than assuming
requested were made.
This response is not the JSON:API resource document the rest of this API returns.
There is no type/id envelope around data, since a batch is not one resource.
controllerId (path, string (uuid), required) Uuid of the controller
application/vnd.api+json
quantity (integer) – How many keys to create201Created
400The server could not understand the request due to invalid syntax.
422The request body failed validation.
500An unexpected error occurred on the server.
PUT /access/controllers/{controllerId}/keys/by-reservation/{stayExternalId}
Brings the key for a stay into line with the reservation as it stands right now, creating it if it does not exist yet. Safe to call repeatedly with the same body.
This is the operation to use when a caller is driving keys from reservation data and
cannot easily track whether it has already created one — a workflow retrying after a
failure, a connector replaying an event, a scheduled reconciliation. Rather than
asking the caller to check first and branch, the key is resolved from
stayExternalId and either created or updated in place.
The pin is never regenerated. Once a pin has been issued for a stay it stays the same for the life of that key, however many times this operation runs. A guest who has been told their pin will not find it changed underneath them.
Each call re-evaluates the request against the controller's current configuration — unit mapping, the unit matrix, timezone handling. Dates that moved, a unit assigned late, or a changed configuration are therefore picked up simply by calling again; there is nothing to replay and no separate reconciliation verb.
externalId in the body must agree with the path. stayExternalId says which
stay is being addressed and the body describes it; if the body carries a different
externalId the request contradicts itself and is refused with 400. Omitting it is
not a disagreement — the path value is used. Send it only if it matches.
Virtual pins. On a controller configured with virtualBefore, a key whose start
is far enough out is created virtual — the pin is returned immediately but is not
written to the locking system yet. Calling this operation once the window has opened
and a unit is assigned writes it to the locking system and flips isVirtual to
false. That is the only way a virtual pin is materialised: there is deliberately no
separate endpoint for it, because materialisation needs the current reservation data
that this request already carries.
Both conditions are needed, so the request that materialises a key must carry
unitName. A virtual key minted before a room was assigned stays virtual until a
call supplies one; a call made after the window has opened but still without a unit is
refused with 422, and the held key is left untouched rather than half-written. Call
again with the unit once the reservation has one.
Interpreting the outcome. Every successful call returns 200 with the key as it
now stands — whether it was created, materialised, or already correct and left
untouched. Do not branch on the status code; read isVirtual to find out whether the
pin is live in the locking system. A 404 means the controller or the stay's key is
gone (a cancelled reservation, for instance) and the caller should stop rather than
retry; 5xx is worth retrying.
controllerId (path, string (uuid), required) Uuid of the controller
stayExternalId (path, string, required) Identifier of the stay in the system the reservation originates from, as sent in
externalId when the key was created. It identifies the key across repeated calls
and is what makes this operation idempotent.
application/vnd.api+json · KeyTypes
unitName (string, required) – name of the lock or doororiginal (boolean, required) – create and replace key if true, copy otherwisestartDate (string (date), required) – Date after which the key is validstartTime (string (time)) – Time after which the key is valid, seconds must be 00endDate (string (date), required) – Date after which the key is invalidendTime (string (time)) – Time after which the key is invalid, seconds must be 00authorizations (string[]) – Add/assign authorization to system defaultdeAuthorizations (string[]) – Remove/deny authorization zone from system defaultextraUnits (string[]) – Additional units to grant access totype (string enum, required)providerId (string (uuid), required) – The provider configuration the key was created with.id (string (uuid), required) – The generated UUIDcreatedAt (string (date-time), required) – Time of creationupdatedAt (string (date-time), required) – Time of last updatekeyType (string, required) – The type of the key200The key as it now stands. Read isVirtual to tell a pin that is live in the
locking system from one that is still only held here.
400The server could not understand the request due to invalid syntax.
404The requested resource could not be found.
422The request body failed validation.
500An unexpected error occurred on the server.
502The upstream access-control system could not carry out the request.
The request itself was well-formed and accepted — this is the locking system, its gateway or its
vendor API failing, being unreachable, or refusing because it is busy. errorCode says which.
Retrying is usually worthwhile, but not immediately: a gateway that answered "busy" is still busy a
second later. Where outcomeUnknown is true the write may have landed despite the failure, so
re-run the idempotent form of the operation rather than assuming nothing happened.
GET /access/keys
Lists all (guest) keys created for all providers.
Any attribute of the key resource can be filtered, and the value is interpreted as
the type of the field it is compared against. controllerId is filterable too,
although it is not part of the returned resource:
| Field | Form | Example |
|---|---|---|
startDate, endDate |
date | filter[startDate][gte]=2026-07-01 |
startTime, endTime |
time | filter[startTime][gte]=14:30:00 |
createdAt, updatedAt |
timestamp, UTC | filter[createdAt][gt]=2026-07-01T12:00:00Z |
controllerId |
id | filter[controllerId][eq]=4d42cfa2-… |
original, isVirtual |
true / false |
filter[isVirtual][eq]=true |
unitName, keyType, externalId, pin, uid |
text | filter[keyType][eq]=pinCode |
A date field may also be given a full timestamp, which is read as that day. A value
that cannot be interpreted as the field's type is answered with 400 naming the
field and the form it expects, rather than being ignored or failing as a server
error.
filter (query, object) Filter results using field/operator pairs. The format is filter[field][operator]=value.
Supported operators: eq, ne, gt, gte, lt, lte, like.
Multiple filters are combined with AND.
page (query, object) Cursor-based pagination. Use page[after] or page[before] with a resource id to navigate pages.
200OK
400The server could not understand the request due to invalid syntax.
500An unexpected error occurred on the server.
GET /access/keys/{keyId}
Get detailed information about one specific key.
keyId (path, string (uuid), required) 200OK
404The requested resource could not be found.
500An unexpected error occurred on the server.
PUT /access/keys/{keyId}
Modify a created key.
Important: Access Control System must support key modification. For physical keys (keycards). This can be accomplished through an updater or by updating the locks (online or by other means). Consider creating a new key instead.
The property providerIdis immutable and cannot be changed.
Physical keycards
If you are trying to modify a key from one access unit to another consider creating a new key instead and also create a new key for the "old" unit to invalidate the previously created key.
The same is true if you are modifying the startDate, endDate, authorization or deAuthorization parameter. You should not modify the original nor the extraUnits parameter in most cases.
Set endDate or endTime parameter to the past to invalidate the key.
Other keys
None physical keys such as pin codes should have lesser restrictions. You should still consider some limitations. Refer to the access control provider implementation documentation.
keyId (path, string (uuid), required) application/vnd.api+json · KeyTypes
unitName (string, required) – name of the lock or doororiginal (boolean, required) – create and replace key if true, copy otherwisestartDate (string (date), required) – Date after which the key is validstartTime (string (time)) – Time after which the key is valid, seconds must be 00endDate (string (date), required) – Date after which the key is invalidendTime (string (time)) – Time after which the key is invalid, seconds must be 00authorizations (string[]) – Add/assign authorization to system defaultdeAuthorizations (string[]) – Remove/deny authorization zone from system defaultextraUnits (string[]) – Additional units to grant access totype (string enum, required)providerId (string (uuid), required) – The provider configuration the key was created with.id (string (uuid), required) – The generated UUIDcreatedAt (string (date-time), required) – Time of creationupdatedAt (string (date-time), required) – Time of last updatekeyType (string, required) – The type of the key204No Content
DELETE /access/keys/{keyId}
Deletes a key.
This endpoint is intended for keys not requiring a physical key being present. An example for such a key is a pin code. Check the documentation of your access control provider implementation whether or not this can invalidate a physical key (keycard).
To delete a physical key, check eraseKey operation instead.
To invalidate a key, consider using PUT instead and set the end to the past.
keyId (path, string (uuid), required) 204No Content
AccessUnits are the physical locks or access control devices. A unit can be a door, a gate, a locker or any other device that can be controlled by an access control system.
GET /access/units
List all access units (locks) of one access-control provider.
filter (query, object) Filter results using field/operator pairs. The format is filter[field][operator]=value.
Supported operators: eq, ne, gt, gte, lt, lte, like.
Multiple filters are combined with AND.
page (query, object) Cursor-based pagination. Use page[after] or page[before] with a resource id to navigate pages.
200OK
400The server could not understand the request due to invalid syntax.
500An unexpected error occurred on the server.
POST /access/units
Adds a new access-control unit to the list. The unit must correspond to an existing unit in the access-control system. Use this method only if the list cannot be populated automatically.
application/vnd.api+json · Unit
Access Control Unit
name (string, required) – common name of the unit or lock.code (string) – Unit id or external code/id as seen in the access-control system.
This is useful if the unit has a name and id in the access-control system and is only use in the api implementation of specific access-control provider.config (object) – Access-control provider specific configuration options, such as the locks possibilities.providerId (string (uuid), required) – The id of the access-control provider that manages this unit.201Created
400The server could not understand the request due to invalid syntax.
422The request body failed validation.
500An unexpected error occurred on the server.
GET /access/units/{unitId}
Get a Unit of the access control system
unitId (path, string (uuid), required) 200OK
404The requested resource could not be found.
500An unexpected error occurred on the server.
PUT /access/units/{unitId}
Update a unit in the access control system
unitId (path, string (uuid), required) application/vnd.api+json · Unit
Access Control Unit
name (string, required) – common name of the unit or lock.code (string) – Unit id or external code/id as seen in the access-control system.
This is useful if the unit has a name and id in the access-control system and is only use in the api implementation of specific access-control provider.config (object) – Access-control provider specific configuration options, such as the locks possibilities.providerId (string (uuid), required) – The id of the access-control provider that manages this unit.204No Content
DELETE /access/units/{unitId}
Delete a unit from the access control system
unitId (path, string (uuid), required) 204No Content