API docs by Redocly

Abloy Keyless Administration API (2.13)

Download OpenAPI specification:

Overview

This API is part of Abloy CUMULUS / BEAT platform for keyless access. The Administration API is intended for administrators to manage resources in their system: locking devices, users, operating devices and permissions. Every API call implicitly targets the system of the authenticated administrator.

Authentication & Authorization

API credentials for an administrator user are required to use this API. Administrators can be created by another administrator in the same system or an integrator user that created the system originally.

API credentials can be exchanged for an access token (JWT) using the login endpoint. The access token must be provided in each request towards other API endpoints in the Authorization header with value Bearer YOUR_TOKEN.

API Keys

All endpoints of this API require an API key. An API key is an application specific key that is associated with rate limits that control how many requests the application is allowed to execute within a certain timeframe. API keys should be kept secret.

The API key must be provided in each request using the X-Api-Key header.

If the key is invalid 403 Forbidden status code is returned.

If the rate-limit is exceeded 429 Too Many Requests status code is returned. In this case the client should consider a strategy that involves less API calls over a short time interval.

Media Types

Every request towards this API must specify the requested media type explicitly using Accept header. This API uses a vendor specific media type that includes the requested API version.

The media type for this API is: application/vnd.assaabloy.keyless.administration-2+json.

Versioning

This API is versioned with a major.minor versioning scheme, but only the major version is included in the Accept header.

Minor version upgrades are backwards compatible and do not require any changes from the API clients. API clients must be implemented in a way that they are not affected by new fields that are added to the responses.

Major versions break backwards compatibility and require API clients to explicitly request the new major version in the Accept header.

Example request

Here's an example of a cURL command that specifies all 3 required headers.

curl -X GET --location "https://eu-api.keyless.assaabloy.com/administration/locking-device" \
  -H "Accept: application/vnd.assaabloy.keyless.administration-2+json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Api-Key: YOUR_API_KEY"

Login

Login

Login with API credentials to obtain an access token required by other API operations. The token is valid for one hour from the time it was created, and can be reused until it expires.

See Authentication & Authorization for information on usage of the token.

Authorizations:
ApiKey
Request Body schema: application/json
userId
required
string <uuid>

Identifier of the user

accessKey
required
string

Access key of the user

Responses

Request samples

Content type
application/json
{
  • "userId": "558aef6a-de33-4e6c-8219-1eab9727ae94",
  • "accessKey": "mA4OKvw59GXsivxQ0TSfg0BISsr94jyYVbNlFVr0Nn4="
}

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "token": "eyJraWQiOiJRNXhWdXA2ZmxISjVUM0pwUXpTYzk0MzhUT0dhaHNWWEppSzZYVmNqRDM0PSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI3MGMxM2M3MS1mZDZlLTRhNjYtYTAwZi1kNTNlMGIwNjA4ZWMiLCJhdWQiOiIxamZ1OWkwcmFxYzJobWg0MTFjZ2lrMWIzOSIsImNvZ25pdG86Z3JvdXBzIjpbInVzZXJzIl0sImV2ZW50X2lkIjoiMjMyMDAzYTYtMGY0Yi00MGU2LTk2MmYtNTA5ZTMwZmI2NTZhIiwidG9rZW5fdXNlIjoiaWQiLCJhdXRoX3RpbWUiOjE1ODA5MDAzNzQsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0xX0Z4dnUzRWtxVyIsImNvZ25pdG86dXNlcm5hbWUiOiJiYjgzMTcwYi05MzRjLTQwZjMtYjEwYy1lMDZjOTBmYmYyODMiLCJleHAiOjE1ODA5MDM5NzQsImlhdCI6MTU4MDkwMDM3NCwiY3VzdG9tOnRlbmFudC1pZCI6IjdlOGU2OGMzLWJjYTMtNDhjMC04ZjI5LWE3NTdlZjJiM2MzZiJ9.gFOduAvbyfFpXBx9rbVDICXF7xk_DFHyv00ssVSvtf2YydH-7odEBG8rJtz-39sYrgCDxhPga6woaqetjJr4wmr6mLbGPLyugd2LhWaOWsmui3K5j-FuZCzV8igCBt6nj9huj1JXGZlrEGXucklmEb1MBcWi7m3wtaQjNaLhuS6UbCFcgpWKCUcGEiLe0LS7538mYcx3IcUMQ2f2704cPOc8a5oXkNNYWUgvnbksyBJovLHSGmVo1lYHS31EtW1IIMMSypfj_Yp9fSgRq3EG8JmwNWBramgyEDBVepRiE8JhA69bb7laZkPQlmMHOBlGTPKjJVfr8sxLr9BXq41itQ"
}

Users

Users can represent either real life persons or access management systems. Every user has API credentials associated with them that allow executing operations depending on the role of the user.

Users can have an operating device that allows them to operate locking devices based on the permissions they've been granted by system administrators.

Users can be created with 2 different roles:

  • USER is intended for real life persons that operate locking devices
  • ADMIN is intended for managing system resources using the Administration API

Get users

Get users of the system.

Authorizations:
(ApiKeyBearerToken)
query Parameters
next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Create a user

Creates a new user with a specified role in the system.

Authorizations:
(ApiKeyBearerToken)
Request Body schema: application/json
role
required
string
Enum: "USER" "ADMIN"

Role of a user

Responses

Request samples

Content type
application/json
{
  • "role": "ADMIN"
}

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "id": "5869ca5a-9423-48f5-8d5f-4a2945a203ec",
  • "accessKey": "8tHva1/oMwJ7F18K4ko3L167QgNzHohsk5PlGY6cYAc=",
  • "role": "ADMIN"
}

Get a user

Gets a user by ID.

Authorizations:
(ApiKeyBearerToken)
path Parameters
user-id
required
string <uuid> (ResourceId)
Example: 558aef6a-de33-4e6c-8219-1eab9727ae94

Identifier of the user

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "id": "5869ca5a-9423-48f5-8d5f-4a2945a203ec",
  • "role": "ADMIN"
}

Delete a user

Deletes a user. This operation will also remove all associated permissions and operating devices.

Authorizations:
(ApiKeyBearerToken)
path Parameters
user-id
required
string <uuid>

Identifier of the user to be deleted

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "Not Found",
  • "status": 404,
  • "detail": "Resource not found",
  • "instance": "http://example.com"
}

Operating Devices

Operating devices can operate locking devices based on permissions granted to their owner user. Operating devices are typically mobile phones with an application that uses the Abloy CUMULUS / BEAT SDK.

Operating devices are invited to the system by delivering an invitation code to the target device. The device can then activate itself by using the Mobile API. During activation, operating device receives API credentials that allow using the Mobile API.

Invite an operating device

Invites a new operating device for the specified user. Unless specified otherwise, an invitation is valid for 24 hours. The invitation is delivered by the platform using a specified delivery mechanism. In case the caller wants to deliver the invitation by other means, delivery method NONE can be used.

Once the operating device accepts the invitation, an OperatingDeviceCreated event is triggered containing the operating device identifier.

More than one operating device invitation can be created for a single user, but user is currently only allowed to have one operating device. This means that an invitation can't be accepted if the user already has an operating device.

Invitation delivery message format

When delivering the invitation via SMS or email, the caller can choose between two formats:

  • INVITATION_LINK - the delivered message will contain an invitation link
  • INVITATION_CODE - the delivered message will contain an invitation code

When using the INVITATION_LINK format, the delivered message will contain a link (https://keyless.assaabloy.com). Users of Abloy BEAT-CUMULUS mobile applications can start the activation process by clicking the link in the message.

When using the INVITATION_CODE format, the delivered message will contain an invitation code. The mobile application user can copy this code and enter it to the application to start the operating device activation process.

Activation by invitation code is only available in newer Keyless Mobile SDKs (Android >= 3.1.0, iOS >= 2.0.0) and newer versions of Abloy BEAT-CUMULUS mobile applications.

See the request body properties and request payload examples for more information.

Notes for Keyless mobile SDK integrators

Older generation of Keyless Mobile SDKs need to activate the operating device with an invitation containing both the invitationCode and environmentUrl. Newer generation of Keyless Mobile SDKs can activate the operating device with only the invitationCode, but then the integrators must use the newer format of the invitationCode provided by the NONE delivery mechanism and using the format request body property set to INVITATION_CODE.

See the request body properties and request and response payload examples for more information.

Authorizations:
(ApiKeyBearerToken)
Request Body schema: application/json
userId
required
string <uuid>

Identifier of the user to invite an operating device for

validityDuration
string <duration>
Default: "PT24H"

Invitation validity in ISO 8601 duration format

Note: Must be greater than 0 seconds and less than or equal to 365 days.

deliveryMechanism
required
string (OperatingDeviceInvitationDeliveryMechanism)

Delivery mechanism for the invitation

  • SMS - Invitation link is delivered via SMS message to the specified phone number
  • EMAIL - Invitation link is delivered via email to the specified email address
  • NONE - Invitation is not delivered automatically, but rather invitation details are returned synchronously in the response. This delivery method is intended for the use of Keyless MobileSDK integration.
phoneNumber
required
string

Mobile phone number in E.164 format

format
string (OperatingDeviceInvitationDeliveryFormat)
Default: "INVITATION_LINK"
Enum: "INVITATION_LINK" "INVITATION_CODE"

Format of the invitation in the delivered message

  • INVITATION_LINK - the delivered sms message will contain an invitation link
  • INVITATION_CODE - the delivered sms message will contain an invitation code

Responses

Request samples

Content type
application/json
Example
{
  • "userId": "be2c1dc6-48ca-4b4a-966e-bf46018cbdc7",
  • "deliveryMechanism": "SMS",
  • "phoneNumber": "+2072325522705"
}

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
Example
{
  • "id": "be2c1dc6-48ca-4b4a-966e-bf46018cbdc7",
  • "expirationDatetime": "2030-01-01T13:00:00Z"
}

Revoke an operating device invitation

Revoke an operating device invitation.

Revoked invitation can't be accepted, and accepted invitations can't be revoked.

Authorizations:
(ApiKeyBearerToken)
path Parameters
invitation-id
required
string <uuid> (InvitationId)
Example: 5155679b-822f-48a1-8e67-a77febff38bd

Identifier of the invitation

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "Not Found",
  • "status": 404,
  • "detail": "Resource not found",
  • "instance": "http://example.com"
}

Get operating devices

Get operating devices of the system. Supports filtering by user ID.

Authorizations:
(ApiKeyBearerToken)
query Parameters
user-id
string <uuid> (ResourceId)
Example: user-id=558aef6a-de33-4e6c-8219-1eab9727ae94

Identifier of the user to filter operating devices by

next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Delete an operating device

Deletes an existing operating device.

Note that if an operating device was not invited using the invite operating device operation of the version 2 of the API, it is considered to be a legacy operating device and it can't be deleted on its own. In this case, the only way to delete the operating device is to delete the corresponding user, which deletes all of the user's operating devices.

Authorizations:
(ApiKeyBearerToken)
path Parameters
operating-device-id
required
string <uuid>

Identifier of the operating device to delete

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "Not Found",
  • "status": 404,
  • "detail": "Resource not found",
  • "instance": "http://example.com"
}

Locking Devices

Locking devices are physical devices (e.g. padlocks, controllers or key deposits) used to secure access points.

Unclaimed and claimed locking devices

When created through the API, a locking device starts out as being unclaimed. An unclaimed locking device acts as a placeholder for a physical locking device.

To connect a physical locking device with an unclaimed locking device, the physical locking device must be claimed using the Mobile API. Claiming is the process where a system takes ownership of a physical locking device. During this process the claiming status of the locking device on the platform transitions from unclaimed to claimed, and information about the physical locking device becomes available (e.g. serial number).

Locking device re-keying

A physical locking device has two key pairs and certificates: operational and manufacturing. Certificates have an expiration date before which the associated key pair has to be rotated and certificate renewed. This process is called re-keying of a locking device certificate. The process is carried out automatically by an operating device when interacting with a locking device that has a certificate eligible for re-keying. If the certificate of the locking device is not re-keyed in time, the locking device will stop being operable.

The process of re-keying works as follows:

  1. A certificate of a locking device becomes eligible for re-keying 1.5 years before its expiration. At this point platform sends a LockingDeviceCertificateEligibleForReKeying notification for subscriptions of the system of the locking device.
  2. When an operating device interacts with a locking device that is eligible for re-keying, it will automatically initiate re-keying process. The locking device generates a new key pair and creates a certificate signing request that is forwarded to platform by the operating device. At this point a LockingDeviceCertificateSigningRequestCreated notification is sent to subscriptions of the system of the locking device.
  3. Platform issues a new certificate for the locking device based on the certificate signing request and sends a LockingDeviceCertificateIssued notification to subscriptions of the system of the locking device.
  4. Operating device forwards the new certificate for the locking device which then installs it. A LockingDeviceCertificateReKeyingCompleted notification is sent to the subscriptions of the system of the locking device.

If the operating device does not have internet access when visiting the locking device, the re-keying process can be executed, but requires two separate visits to the locking device. On first visit the certificate signing request is created, and on the second visit the issued certificate is installed.

Get locking devices

Returns locking devices of the system. Supports filtering by claiming status and serial number.

Authorizations:
(ApiKeyBearerToken)
query Parameters
claiming-status
string (ClaimingStatus)
Enum: "UNCLAIMED" "CLAIMED"
Example: claiming-status=UNCLAIMED

Claiming status of the locking device

serial-number
string
Example: serial-number=BPLAD123456

Serial number of the locking device

Unclaimed locking devices do not have serial number.

next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Create an unclaimed locking device

Creates an unclaimed locking device to the system. Unclaimed locking device is not yet connected to a physical locking device.

In order to claim a physical locking device, an operating device has to interact with it and connect it with an unclaimed locking device on the platform by using the mobile API.

Authorizations:
(ApiKeyBearerToken)
Request Body schema: application/json
name
required
string [ 1 .. 255 ] characters

Name of the locking device

Responses

Request samples

Content type
application/json
{
  • "name": "Front Gate"
}

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "id": "02828588-2c7f-4847-b011-e489eb01f872",
  • "name": "Front Gate",
  • "claimingStatus": "UNCLAIMED"
}

Update a locking device

Updates an existing locking device. Request body is in JSON Patch format.

Note: Currently only the field name can be changed with operation replace.

Authorizations:
(ApiKeyBearerToken)
path Parameters
locking-device-id
required
string <uuid> (ResourceId)
Example: 558aef6a-de33-4e6c-8219-1eab9727ae94

Identifier of the locking device to modify

Request Body schema: application/json-patch+json
Array
One of
path
required
string

JSON Pointer path

op
required
string
Enum: "add" "replace" "test"

The operation to perform

value
required
any

The value to add, replace or test

Responses

Request samples

Content type
application/json-patch+json
[
  • {
    }
]

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "Not Found",
  • "status": 404,
  • "detail": "Resource not found",
  • "instance": "http://example.com"
}

Get a locking device

Gets a single locking device by ID.

Authorizations:
(ApiKeyBearerToken)
path Parameters
locking-device-id
required
string <uuid> (ResourceId)
Example: 558aef6a-de33-4e6c-8219-1eab9727ae94

Identifier of the locking device

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
Example
{
  • "id": "02828588-2c7f-4847-b011-e489eb01f872",
  • "name": "Front Gate",
  • "claimingStatus": "UNCLAIMED"
}

Delete a locking device

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Deletes a locking device from the system.

In most cases, it is recommended to use this operation to delete only unclaimed locking devices. Deleting a claimed locking device is a destructive operation, as it won't be possible to assign permissions to operate a deleted locking device anymore. For this reason, it is only recommended to delete a claimed locking device if it is taken permanently out of service.

Notice that it is not currently possible to reclaim a claimed locking device that has been deleted.

Any entities associated with the deleted locking device will be removed automatically by the Keyless Platform.

Authorizations:
(ApiKeyBearerToken)
path Parameters
locking-device-id
required
string <uuid> (ResourceId)
Example: 558aef6a-de33-4e6c-8219-1eab9727ae94

Identifier of the locking device

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "Not Found",
  • "status": 404,
  • "detail": "Resource not found",
  • "instance": "http://example.com"
}

Locking Device Log

Locking devices produce log entries. Log entries can be either system log entries or audit log entries.

System log entries are logged for internal events of a locking device, such as the locking device having booted up.

Audit log entries are logged for each ThingRPC conversation that the operating device has executed on a locking device.

Log entries are submitted to the Keyless Platform by the operating device at the start of, and during its connection to the locking device. The platform processes the log entries and publishes notifications for the system integrator to consume. Log entries are also available for querying through the API.

Get system log of a locking device

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Get system log of the specified locking device.

Results are sorted by occurrenceDatetime and id in ascending order by default, i.e. oldest entries are returned first. The sort-direction parameter can be used to change the sort order.

Authorizations:
(ApiKeyBearerToken)
query Parameters
locking-device-id
string <uuid> (LockingDeviceId)
Example: locking-device-id=8d93b9e0-351d-40d3-a6d5-39d408bf9680

Identifier of the locking device to get logs from

sequence-number-greater-than
integer >= 0
Example: sequence-number-greater-than=10

Only return system log entries with a sequence number greater than the specified value

after-datetime
string <date-time>

Only return system log entries that happened after the specified time

next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

sort-direction
string
Default: "ASC"
Enum: "ASC" "DESC"
Example: sort-direction=ASC

Sort direction

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Get audit log of a locking device

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Get audit log of the specified locking device.

Results are sorted by occurrenceDatetime and id in ascending order by default, i.e. oldest entries are returned first. The sort-direction parameter can be used to change the sort order.

Note: The earliest audit log entries available through this endpoint are from December 18th 2024.

Authorizations:
(ApiKeyBearerToken)
query Parameters
locking-device-id
string <uuid> (LockingDeviceId)
Example: locking-device-id=8d93b9e0-351d-40d3-a6d5-39d408bf9680

Identifier of the locking device to get logs from

sequence-number-greater-than
integer >= 0
Example: sequence-number-greater-than=10

Only return audit log entries with a sequence number greater than the specified value

after-datetime
string <date-time>

Only return audit log entries that happened after the specified time

next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

sort-direction
string
Default: "ASC"
Enum: "ASC" "DESC"
Example: sort-direction=ASC

Sort direction

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Permissions

Permissions are associations between users and locking devices. They authorize the user to execute operations on a locking device within specified time intervals.

Users are able to fetch operating keys with their operating devices for the locking devices they have permissions to operate.

Past permissions are automatically removed 14 days after their expiration.

Grant a permission

Grants the user a permission to perform specific operations on a locking device.

Authorizations:
(ApiKeyBearerToken)
Request Body schema: application/json
userId
required
string <uuid>

Identifier of the user to grant the permission for

lockingDeviceId
required
string <uuid>

Identifier of the locking device to grant the permission for

operationType
required
string (OperationType)
Enum: "OPEN" "UPDATE_FIRMWARE" "UPDATE_TIME"

The type of the operation for which the permission is given

  • OPEN - Permission to open and update the time of the locking device.
  • UPDATE_FIRMWARE - Permission to update the firmware, to open and to update the time of the locking device.
  • UPDATE_TIME - Permission to update the time of the locking device.
permissionType
required
string (PermissionType)

Permission type

  • SINGLE_INTERVAL - The permission is valid between the specified start and end time.
  • MULTIPLE_INTERVALS - The permission is valid within multiple specified time intervals.
  • RECURRING (Deprecated) - The permission is valid on specified time intervals on specified weekdays.
operatingKeyValidityDuration
string <duration> (OperatingKeyValidityDuration)
Default: "P8D"

Validity duration (ISO 8601) of an operating key generated based on the permission

Operating key validity duration defines how long an operating key downloaded for offline use is valid for. Even if a user would have a permission to open a locking device for a period of 1 year, when they download an operating key based on this permission, that operating key will only be valid for 8 days by default. After that, they need to download operating keys again.

Setting a long validity duration has a downside from security perspective, as revoking a permission does not affect the already downloaded operating key. Setting a short validity duration is most secure, but can be problematic in areas without internet connectivity.

Note: Must be greater than or equal to 1 day and less than or equal to 31 days.

start
required
string <date-time>

Start datetime (ISO 8601) of the permission

end
required
string <date-time>

End datetime (ISO 8601) of the permission

Responses

Request samples

Content type
application/json
Example
{
  • "permissionType": "SINGLE_INTERVAL",
  • "userId": "6c8307d3-e8f5-4946-a5dd-70a5865d6c04",
  • "lockingDeviceId": "0a323b61-0497-4865-991c-c1420aa2d829",
  • "operationType": "OPEN",
  • "operatingKeyValidityDuration": "P8D",
  • "start": "2023-09-02T15:00:00Z",
  • "end": "2023-09-02T18:00:00Z"
}

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "id": "eee5c5cf-8bce-4876-8fab-2197cbb78426"
}

Get permissions

Get permissions of the system.

Authorizations:
(ApiKeyBearerToken)
query Parameters
next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
Example
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Update an existing permission

This operation updates a permission. Every field of the specified permission is changed but it will retain its old identifier.

Authorizations:
(ApiKeyBearerToken)
path Parameters
permission-id
required
string <uuid> (ResourceId)
Example: 558aef6a-de33-4e6c-8219-1eab9727ae94

Identifier of the permission to update

Request Body schema: application/json
userId
required
string <uuid>

Identifier of the user to grant the permission for

lockingDeviceId
required
string <uuid>

Identifier of the locking device to grant the permission for

operationType
required
string (OperationType)
Enum: "OPEN" "UPDATE_FIRMWARE" "UPDATE_TIME"

The type of the operation for which the permission is given

  • OPEN - Permission to open and update the time of the locking device.
  • UPDATE_FIRMWARE - Permission to update the firmware, to open and to update the time of the locking device.
  • UPDATE_TIME - Permission to update the time of the locking device.
permissionType
required
string (PermissionType)

Permission type

  • SINGLE_INTERVAL - The permission is valid between the specified start and end time.
  • MULTIPLE_INTERVALS - The permission is valid within multiple specified time intervals.
  • RECURRING (Deprecated) - The permission is valid on specified time intervals on specified weekdays.
operatingKeyValidityDuration
string <duration> (OperatingKeyValidityDuration)
Default: "P8D"

Validity duration (ISO 8601) of an operating key generated based on the permission

Operating key validity duration defines how long an operating key downloaded for offline use is valid for. Even if a user would have a permission to open a locking device for a period of 1 year, when they download an operating key based on this permission, that operating key will only be valid for 8 days by default. After that, they need to download operating keys again.

Setting a long validity duration has a downside from security perspective, as revoking a permission does not affect the already downloaded operating key. Setting a short validity duration is most secure, but can be problematic in areas without internet connectivity.

Note: Must be greater than or equal to 1 day and less than or equal to 31 days.

start
required
string <date-time>

Start datetime (ISO 8601) of the permission

end
required
string <date-time>

End datetime (ISO 8601) of the permission

Responses

Request samples

Content type
application/json
Example
{
  • "permissionType": "SINGLE_INTERVAL",
  • "userId": "6c8307d3-e8f5-4946-a5dd-70a5865d6c04",
  • "lockingDeviceId": "0a323b61-0497-4865-991c-c1420aa2d829",
  • "operationType": "OPEN",
  • "operatingKeyValidityDuration": "P8D",
  • "start": "2023-09-02T15:00:00Z",
  • "end": "2023-09-02T18:00:00Z"
}

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "Not Found",
  • "status": 404,
  • "detail": "Resource not found",
  • "instance": "http://example.com"
}

Revoke a permission

Revokes user's permission to operate a locking device.

Authorizations:
(ApiKeyBearerToken)
path Parameters
permission-id
required
string <uuid> (ResourceId)
Example: 558aef6a-de33-4e6c-8219-1eab9727ae94

Identifier of the permission to revoke

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "Not Found",
  • "status": 404,
  • "detail": "Resource not found",
  • "instance": "http://example.com"
}

Get permission

Get permission by permission id.

Authorizations:
(ApiKeyBearerToken)
path Parameters
permission-id
required
string <uuid> (ResourceId)
Example: 558aef6a-de33-4e6c-8219-1eab9727ae94

Identifier of the permission

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
Example
{
  • "id": "8f6fc5b0-1a48-4803-8f44-d6e302cd502b",
  • "permissionType": "SINGLE_INTERVAL",
  • "userId": "6c8307d3-e8f5-4946-a5dd-70a5865d6c04",
  • "lockingDeviceId": "0a323b61-0497-4865-991c-c1420aa2d829",
  • "operationType": "OPEN",
  • "operatingKeyValidityDuration": "P8D",
  • "start": "2023-09-02T15:00:00Z",
  • "end": "2023-09-02T18:00:00Z"
}

Offline keys

Offline keys allow operating devices to receive operating keys and operate locking devices in areas with no internet access.

Offline keys are ad-hoc constructs. Similarly to permissions, they have a validity period, a start and an end time. A key can only be used within its validity. Once the end time is reached, the key is considered expired, cannot be used anymore and can be discarded. Only a newly generated offline key can be used after the expiration.

The keys are unique per operating device and locking device. If a key is generated for specific operating device and a specific locking device, it cannot be used by any other operating device to operate any other locking device. Offline keys support only basic locking device operations (opening and locking).

The keys can either be delivered via the Keyless platform SMS delivery mechanism or generated and delivered by own means.

Note:

  • For an operating device to be able to receive and digest offline keys, it is required that the device has a mobile application using Keyless mobileSDK installed. The operating device must also be registered to the same system as the locking device.

Issue offline key

Issue an offline key for an operating device to operate a locking device.

Delivering offline keys

When issuing offline keys, one can choose to use one of the following delivery mechanisms NONE, SMS_WITHOUT_APP_LINK, SMS_WITH_APP_LINK. This delivery mechanism is set in the request body.

Generating offline keys with NONE

When choosing NONE as delivery mechanism, the offline key will only be generated and synchronously returned in the response body. This mechanism should be chosen, when one wants to deliver the keys using one's own means.

When choosing SMS_WITHOUT_APP_LINK as delivery mechanism, the offline key raw values will be delivered via the platform's SMS delivery system. The key values will also be returned synchronously in the response body. This mechanism should be chosen, when one wants to deliver only the raw values of the keys.

When choosing SMS_WITH_APP_LINK as delivery mechanism, the offline keys will be delivered via the platform's SMS delivery system as app links. The key values will also be returned synchronously in the response body.

An offline key app link in an SMS message looks like the following: <appLinkBaseUrl>?eo=<offlineKeyRawValue>, where:

  • the <appLinkBaseUrl> is a valid URL and can be set in the request body. If the request body property is omitted, a default value of "https://keyless.assaabloy.com" will be used. If mobile application users are using the BEAT mobile applications, one should omit the property.
  • <offlineKeyRawValue> is the raw value of the offline key. The same value that is present in the response body.

The benefit of delivering app links via SMS, is to give end users the ability to automatically open a mobile application when clicking on the received SMS message link. On Android and iOS platforms mobile application developers can register certain URIs to automatically open a specific application. Refer to the following documentations in how to configure mobile application to work with app links:


Important notes

Offline keys support only basic locking device operations - unlocking and locking. Additionally, offline keys give the operating devices' possibility to distribute audit logs from the locking devices into the platform. They do not, however, give the possibility to execute administrative operations such as locking device audit log deletion, locking device firmware upgrades or locking device certificate updates. These operations are only available when using the permissions framework for operating locking devices. Operating using the permission framework is must in keeping the locking devices operational.

In addition to the primary offline key, the response may contain an alternative key. Alternative key is issued in a case where the platform does not yet know whether the offline locking device has changed to using a new certificate (e.g. certificate re-keying). When the response contains the alternative key, both the primary and alternative ones should be given to the operating device.

Authorizations:
(ApiKeyBearerToken)
Request Body schema: application/json
operatingDeviceId
required
string <uuid>

Identifier of the operating device to grant the offline keys for

lockingDeviceId
required
string <uuid>

Identifier of the locking device to grant the offline keys to

startDatetime
required
string <date-time> (OfflineKeyStart)

Start date and time of the offline key (ISO 8601).

The start date time cannot be more than 30 days in the future.

endDatetime
required
string <date-time> (OfflineKeyEnd)

End date and time of the offline key (ISO 8601).

The end date time cannot be more than 24 hours after start date time.

appLinkBaseUrl
string <URL> (OfflineKeyAppLinkBaseUrlSchema) <= 42 characters
Default: "https://keyless.assaabloy.com"

Optional base url for offline key app links with maximum length of 42 characters.

Refer to Delivering offline key app links with SMS_WITH_APP_LINK for more details.

deliveryMechanism
required
string (OfflineKeysDeliveryMechanism)

Delivery mechanism for the offline keys

  • SMS_WITH_APP_LINK - Keys are delivered as app links via SMS to the specified phone number.
  • SMS_WITHOUT_APP_LINK - Raw key values are delivered via SMS to the specified phone number.
  • NONE - Keys are not delivered automatically, but rather they are generated and returned synchronously in the response.
phoneNumber
required
string

Mobile phone number in E.164 format.

The Keyless platform will send an SMS to this phone number. The SMS will contain an app link to digest the generated offline keys.

Responses

Request samples

Content type
application/json
Example
{
  • "operatingDeviceId": "07ca923d-80af-40d1-ae3c-31b0477ad648",
  • "lockingDeviceId": "c4d85dba-913b-49bc-ab0a-4a1031b118d1",
  • "startDatetime": "2023-12-24T18:00:00Z",
  • "endDatetime": "2020-12-31T23:59:59Z",
  • "deliveryMechanism": "SMS_WITH_APP_LINK",
  • "appLinkBaseUrl": "https://a-custom-domain.com",
  • "phoneNumber": "+358506722871"
}

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
Example
{
  • "primaryKey": {
    },
  • "startDatetime": "2023-12-24T18:00:00Z",
  • "endDatetime": "2023-12-31T23:59:59Z"
}

Get offline keys metadata

Get metadata of the offline keys issued in the system.

For security reasons metadata does not contain the key value that could be used to open a locking device.

Authorizations:
(ApiKeyBearerToken)
query Parameters
next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Gateway Devices

Gateway is an internet connected device that allows remotely controlling locking devices using remote commands.

Gateway devices are claimed into a system by an administrator. Claiming is the process where a system takes ownership of a physical gateway device. Once claimed, the gateway device first has an activation status of PENDING_ACTIVATION. When the gateway device is powered on, it will attempt to activate itself on the Keyless Platform. When the activation is successful, the gateway device activation status changes to ACTIVE. Gateway device activation triggers a GatewayDeviceActivated notification.

In order for a gateway device to be able to control a locking device, it must be associated with the locking device first.

An activated gateway device reports system and audit logs to the Keyless Platform. See Gateway Device Log for more information.

Gateway device ownership can be transferred to another system by following these steps:

  1. Delete the gateway device from the current system.
  2. Perform a factory reset for the physical gateway device.
  3. Claim the gateway device into the new system.

Claim a gateway device

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Claims a physical gateway device into the system.

Claiming is the process where a system takes ownership of a physical gateway device. Once claimed, the gateway device first has an activation status of PENDING_ACTIVATION. When the gateway device is powered on, it will attempt to activate itself on the Keyless Platform. When the activation is successful, the gateway device activation status changes to ACTIVE. Gateway device activation triggers a GatewayDeviceActivated notification.

Claiming a gateway device requires a claiming code. Claiming code is printed on a label in the back of the physical gateway device.

Authorizations:
(ApiKeyBearerToken)
Request Body schema: application/json
claimingCode
required
string (GatewayDeviceClaimingCode)

Claiming code of the gateway device

Claiming code is printed on the gateway device and allows a system administrator to claim the gateway device into their system.

Responses

Request samples

Content type
application/json
{
  • "claimingCode": "2K7H-ASR3"
}

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "id": "c78afb03-a06e-4da9-afca-edce82ffad9f",
  • "serialNumber": "BGWA1DD2E00004",
  • "activationStatus": "PENDING_ACTIVATION",
  • "creationDatetime": "2019-08-24T14:15:22Z"
}

Get gateway devices

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Returns gateway devices of the system.

Authorizations:
(ApiKeyBearerToken)
query Parameters
next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Get a gateway device

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Gets a single gateway device by ID.

Authorizations:
(ApiKeyBearerToken)
path Parameters
gateway-device-id
required
string <uuid> (GatewayDeviceId)
Example: c78afb03-a06e-4da9-afca-edce82ffad9f

Identifier of the gateway device

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
Example
{
  • "id": "806c4be9-7b48-4cfa-9c83-9584ad1d4def",
  • "serialNumber": "BGWA1DD2E00004",
  • "activationStatus": "PENDING_ACTIVATION",
  • "creationDatetime": "2024-01-01T08:00:00Z"
}

Delete a gateway device

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Deletes a gateway device from the system.

Deleting a gateway device from the system and then doing a factory reset for the gateway device will allow the gateway device to be re-claimed.

Authorizations:
(ApiKeyBearerToken)
path Parameters
gateway-device-id
required
string <uuid> (GatewayDeviceId)
Example: c78afb03-a06e-4da9-afca-edce82ffad9f

Identifier of the gateway device to be deleted

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "Not Found",
  • "status": 404,
  • "detail": "Resource not found",
  • "instance": "http://example.com"
}

Gateway Device Log

Gateway devices produce log entries. Log entries can be either system log entries or audit log entries.

System log entries are logged for internal events of a gateway device, such as the gateway device having booted up.

Audit log entries are logged for each ThingRPC conversation that the gateway device has executed on a locking device.

Log entries are submitted to the Keyless Platform by the gateway device whenever it is woken up by a locking device or a scheduled wake-up once per day. The platform processes the log entries and publishes notifications for the system integrator to consume. Log entries are also available for querying through the API.

Get system log of a gateway device

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Get system log of the specified gateway device.

Results are sorted by datetime and sequence number in ascending order by default, i.e. oldest entries are returned first. The sort-direction parameter can be used to change the sort order.

Authorizations:
(ApiKeyBearerToken)
query Parameters
gateway-device-id
required
string <uuid> (GatewayDeviceId)
Example: gateway-device-id=c78afb03-a06e-4da9-afca-edce82ffad9f

Identifier of the gateway device to get logs from

sequence-number-greater-than
integer >= 0
Example: sequence-number-greater-than=10

Only return system log entries with a sequence number greater than the specified value

next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

sort-direction
string
Default: "ASC"
Enum: "ASC" "DESC"
Example: sort-direction=ASC

Sort direction

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Get audit log of a gateway device

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Get audit log of the specified gateway device.

Results are sorted by datetime and sequence number in ascending order by default, i.e. oldest entries are returned first. The sort-direction parameter can be used to change the sort order.

Authorizations:
(ApiKeyBearerToken)
query Parameters
gateway-device-id
required
string <uuid> (GatewayDeviceId)
Example: gateway-device-id=c78afb03-a06e-4da9-afca-edce82ffad9f

Identifier of the gateway device to get logs from

sequence-number-greater-than
integer >= 0
Example: sequence-number-greater-than=10

Only return audit log entries with a sequence number greater than the specified value

next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

sort-direction
string
Default: "ASC"
Enum: "ASC" "DESC"
Example: sort-direction=ASC

Sort direction

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Gateway Device Associations

Gateway device can be associated with multiple locking devices. Associations define which locking devices a gateway device is able to control: either by executing remote commands or by performing periodic log collection and other maintenance operations.

Gateway device associations are managed by an administrator. Associations can be created even if the locking device isn't claimed yet or the gateway device isn't activated yet.

Gateway device can be associated with a maximum of 5 locking devices at the same time.

Create a gateway device association

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Associates a locking device with a gateway device.

Note: The Keyless Platform currently allows 6 associations per gateway device.

Authorizations:
(ApiKeyBearerToken)
Request Body schema: application/json
gatewayDeviceId
required
string <uuid>

Identifier of the gateway device to associate a locking device with

lockingDeviceId
required
string <uuid>

Identifier of the locking device to associate with the gateway

Responses

Request samples

Content type
application/json
{
  • "gatewayDeviceId": "c78afb03-a06e-4da9-afca-edce82ffad9f",
  • "lockingDeviceId": "8d93b9e0-351d-40d3-a6d5-39d408bf9680"
}

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "id": "2fb4767c-c4a4-44aa-aadb-2f58a761085a",
  • "gatewayDeviceId": "c78afb03-a06e-4da9-afca-edce82ffad9f",
  • "lockingDeviceId": "8d93b9e0-351d-40d3-a6d5-39d408bf9680",
  • "creationDatetime": "2019-08-24T14:15:22Z"
}

Get gateway device associations

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Returns gateway device associations of the system. Supports filtering by gateway device ID.

Authorizations:
(ApiKeyBearerToken)
query Parameters
gateway-device-id
string <uuid> (GatewayDeviceId)
Example: gateway-device-id=c78afb03-a06e-4da9-afca-edce82ffad9f

Identifier of the gateway device to filter gateway device associations by

next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Get a gateway device association

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Gets a single gateway device association by ID.

Authorizations:
(ApiKeyBearerToken)
path Parameters
gateway-device-association-id
required
string <uuid> (GatewayDeviceAssociationId)
Example: 2fb4767c-c4a4-44aa-aadb-2f58a761085a

Identifier of the gateway device association

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "id": "2fb4767c-c4a4-44aa-aadb-2f58a761085a",
  • "gatewayDeviceId": "c78afb03-a06e-4da9-afca-edce82ffad9f",
  • "lockingDeviceId": "8d93b9e0-351d-40d3-a6d5-39d408bf9680",
  • "creationDatetime": "2019-08-24T14:15:22Z"
}

Delete a gateway device association

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Deletes a gateway device association.

Authorizations:
(ApiKeyBearerToken)
path Parameters
gateway-device-association-id
required
string <uuid> (GatewayDeviceAssociationId)
Example: 2fb4767c-c4a4-44aa-aadb-2f58a761085a

Identifier of the gateway device association to be deleted

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "Not Found",
  • "status": 404,
  • "detail": "Resource not found",
  • "instance": "http://example.com"
}

Remote Commands

Remote commands instruct gateway devices to execute actions on locking devices.

Remote commands are read by the gateway device whenever it is woken up by a locking device that is associated with it. Command is visible to a gateway device only if the validity period of the command has not ended and the command has not been canceled or acknowledged. After a gateway device reads a command, it will acknowledge it to the Keyless Platform. After acknowledging the command, gateway device will proceed to execute the command. RemoteCommandAcknowledged notification is sent when the command is acknowledged by the gateway device.

A command read by the gateway device contains an operating key that allows the gateway device to operate the locking device within validity period of the command. Even if the gateway device reads a command before its validity period ends, it won't be able to successfully execute the command outside the validity period.

Gateway device audit and system log entries should be relied on for reporting the actions performed by the gateway device in response to a command. Acknowledgement itself does not mean that the command execution was successful, it only means that the gateway device will attempt to execute the command.

Issue a remote command

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Issues a remote command that is valid for 5 minutes.

Remote command can only be issued targeting a locking device that is associated with the specified gateway device. Additionally, the gateway device must be activated and the locking device must be claimed.

Authorizations:
(ApiKeyBearerToken)
Request Body schema: application/json
gatewayDeviceId
required
string <uuid>

Identifier of the gateway device that executes the remote command

lockingDeviceId
required
string <uuid>

Identifier of the locking device that the command targets

action
required
string (RemoteCommandActionEnum)
Value: "OPEN"

Action to be executed by the gateway device in response to the remote command

  • OPEN - Gateway device opens the locking device.

Responses

Request samples

Content type
application/json
{
  • "gatewayDeviceId": "c78afb03-a06e-4da9-afca-edce82ffad9f",
  • "lockingDeviceId": "8d93b9e0-351d-40d3-a6d5-39d408bf9680",
  • "action": "OPEN"
}

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "id": "de037108-e305-4e69-9be2-91260ca712df",
  • "gatewayDeviceId": "c78afb03-a06e-4da9-afca-edce82ffad9f",
  • "lockingDeviceId": "8d93b9e0-351d-40d3-a6d5-39d408bf9680",
  • "action": "OPEN",
  • "validityStartDatetime": "2019-08-24T14:15:22Z",
  • "validityEndDatetime": "2019-08-24T14:15:22Z",
  • "issuerUserId": "3adb41ba-8023-4357-9660-a042e156db7c",
  • "issuanceDatetime": "2019-08-24T14:15:22Z",
  • "acknowledgementDatetime": "2019-08-24T14:15:22Z",
  • "cancelerUserId": "3adb41ba-8023-4357-9660-a042e156db7c",
  • "cancellationDatetime": "2019-08-24T14:15:22Z"
}

Get remote commands

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Returns remote commands issued within the system. Supports filtering by gateway device ID.

Authorizations:
(ApiKeyBearerToken)
query Parameters
gateway-device-id
string <uuid> (GatewayDeviceId)
Example: gateway-device-id=c78afb03-a06e-4da9-afca-edce82ffad9f

Identifier of the gateway device to filter remote commands by

next-page-token
string
Example: next-page-token=VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==

The next page token received from the previous request

limit
integer <int32> [ 1 .. 100 ]
Default: 50

Amount of items per page

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "nextPageToken": "VHpVZEpDeVg1N2RYNFFoSWk4bkIycGVGWTZWRThqcQ==",
  • "items": [
    ]
}

Get a remote command

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Gets a single remote command by ID.

Authorizations:
(ApiKeyBearerToken)
path Parameters
remote-command-id
required
string <uuid> (RemoteCommandId)
Example: de037108-e305-4e69-9be2-91260ca712df

Identifier of the remote command

Responses

Response samples

Content type
application/vnd.assaabloy.keyless.administration-2+json
{
  • "id": "de037108-e305-4e69-9be2-91260ca712df",
  • "gatewayDeviceId": "c78afb03-a06e-4da9-afca-edce82ffad9f",
  • "lockingDeviceId": "8d93b9e0-351d-40d3-a6d5-39d408bf9680",
  • "action": "OPEN",
  • "validityStartDatetime": "2019-08-24T14:15:22Z",
  • "validityEndDatetime": "2019-08-24T14:15:22Z",
  • "issuerUserId": "3adb41ba-8023-4357-9660-a042e156db7c",
  • "issuanceDatetime": "2019-08-24T14:15:22Z",
  • "acknowledgementDatetime": "2019-08-24T14:15:22Z",
  • "cancelerUserId": "3adb41ba-8023-4357-9660-a042e156db7c",
  • "cancellationDatetime": "2019-08-24T14:15:22Z"
}

Cancel a remote command

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Cancel a remote command by ID.

A canceled remote command will not be executed by a gateway device.

Cancellation is only possible if the remote command has not been acknowledged or canceled yet.

Authorizations:
(ApiKeyBearerToken)
path Parameters
remote-command-id
required
string <uuid> (RemoteCommandId)
Example: de037108-e305-4e69-9be2-91260ca712df

Identifier of the remote command

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "Not Found",
  • "status": 404,
  • "detail": "Resource not found",
  • "instance": "http://example.com"
}

Webhooks

System integrator is able to subscribe to webhooks that are triggered when events occur in their system.

Information about the subscription process is available in the Integration API documentation.

UserCreated Webhook

Triggered when a user has been created.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "UserCreated"

Type of the event

userId
required
string <uuid>

Identifier of the created user

role
required
string
Enum: "USER" "ADMIN"

Role of the created user

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "UserCreated",
  • "userId": "8c5be808-d23b-4c06-9d32-0f985d1d88f2",
  • "role": "USER"
}

UserDeleted Webhook

Triggered when a user has been deleted.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "UserDeleted"

Type of the event

userId
required
string <uuid>

Identifier of the deleted user

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "UserDeleted",
  • "userId": "bfe1d6a1-6c3b-497a-b35d-68ecc0fa8a9d"
}

OperatingDeviceCreated Webhook

Triggered when an operating device has been created.

Operating devices are created when an operating device invitation sent by a system administrator is accepted. At this step the operating device has received API credentials, but has not yet been provisioned an operational certificate that is needed for example for receiving operating keys from the platform. When the operating device has received an operational certificate, the OperatingDeviceActivated event is triggered.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "OperatingDeviceCreated"

Type of the event

operatingDeviceId
required
string <uuid>

Identifier of the created operating device

userId
required
string <uuid>

Identifier of the user that owns the operating device

invitationId
required
string <uuid>

Identifier of the invitation the operating device was created with

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "OperatingDeviceCreated",
  • "operatingDeviceId": "c50ae5cc-d3ea-447b-a2a9-86ffbb6e41b3",
  • "userId": "8c5be808-d23b-4c06-9d32-0f985d1d88f2",
  • "invitationId": "23d92cc4-ce69-49f8-8c2f-bf90536b5dbf"
}

OperatingDeviceActivated Webhook

Triggered when an operating device has been activated.

Operating devices are activated when they receive an operational certificate. After activation, operating devices can receive operating keys from the platform and can operate locking devices.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "OperatingDeviceActivated"

Type of the event

operatingDeviceId
required
string <uuid>

Identifier of the activated operating device

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "OperatingDeviceActivated",
  • "operatingDeviceId": "c50ae5cc-d3ea-447b-a2a9-86ffbb6e41b3"
}

OperatingDeviceDeleted Webhook

Triggered when an operating device has been deleted.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "OperatingDeviceDeleted"

Type of the event

operatingDeviceId
required
string <uuid>

Identifier of the deleted operating device

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "OperatingDeviceDeleted",
  • "operatingDeviceId": "c50ae5cc-d3ea-447b-a2a9-86ffbb6e41b3"
}

LockingDeviceClaimed Webhook

Triggered when a locking device has been claimed.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "LockingDeviceClaimed"

Type of the event

lockingDeviceId
required
string <uuid>

Identifier of the locking device that was claimed

userId
required
string <uuid>

Identifier of the user that claimed the locking device

serialNumber
required
string

Serial number of the locking device that was claimed

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "LockingDeviceClaimed",
  • "lockingDeviceId": "688674e3-f5bd-489e-b7c0-1970d5d96020",
  • "userId": "9ee5b1c1-e31d-4d3a-a85a-d6c53a69b1d7",
  • "serialNumber": "BPLAD123456"
}

LockingDeviceSystemLogEntryReceived Webhook

Triggered when the platform receives a system log entry from a locking device.

System log entries are logged for locking device internal events such as the locking device has booted up or that the certificate of the locking device has changed.

Log entries are delivered to the platform by operating devices.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "LockingDeviceSystemLogEntryReceived"

Type of the event

logEntryId
required
string <uuid>

Identifier of the log entry

logEntryEventName
required
string

Name of the event emitted by the locking device

logEntryDatetime
required
string <date-time>

Datetime (ISO 8601) the event occurred at in the locking device

logEntrySequenceNumber
required
integer

Running number that is incremented every time a new log entry occurs in the locking device

lockingDeviceId
required
string <uuid>

Identifier of the locking device that the log entry originates from

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "LockingDeviceSystemLogEntryReceived",
  • "logEntryId": "558aef6a-de33-4e6c-8219-1eab9727ae94",
  • "logEntryEventName": "BATTERY_LOW",
  • "logEntryDatetime": "2019-08-24T14:15:22Z",
  • "logEntrySequenceNumber": 101,
  • "lockingDeviceId": "558aef6a-de33-4e6c-8219-1eab9727ae94"
}

LockingDeviceAuditLogEntryReceived Deprecated Webhook

Deprecated

This webhook is not delivered when the locking device is operated by a gateway device. Use LockingDeviceAuditLogEntryReceivedV2 instead, which is delivered for all operations on locking devices.

Triggered when the platform receives a locking device audit log entry from a locking device.

Audit log entries are logged for all operations that operating devices execute on locking devices. This event is not sent when the locking device is operated by a gateway device.

Log entries are delivered to the platform by operating devices.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "LockingDeviceAuditLogEntryReceived"

Type of the event

logEntryId
required
string <uuid>

Identifier of the log entry

logEntryEventName
required
string

Name of the operation executed by the operating device

Technically this maps to the name of the performed ThingRPC conversation.

logEntryDatetime
required
string <date-time>

Datetime (ISO 8601) the event occurred at in the locking device

logEntrySequenceNumber
required
integer

Running number that is incremented every time a new log entry occurs in the locking device

lockingDeviceId
required
string <uuid>

Identifier of the locking device that the log entry originates from

operatingDeviceId
required
string <uuid>

Identifier of the operating device that was used to operate the locking device

userId
required
string <uuid>

Identifier of the user that owns the operating device that was used to operate the locking device

granted
required
boolean

Indicates that the operating device that attempted to execute the operation had a valid operating key with sufficient permissions and that the operation was therefore permitted

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "LockingDeviceAuditLogEntryReceived",
  • "logEntryId": "558aef6a-de33-4e6c-8219-1eab9727ae94",
  • "logEntryEventName": "unlock",
  • "logEntryDatetime": "2019-08-24T14:15:22Z",
  • "logEntrySequenceNumber": 101,
  • "lockingDeviceId": "558aef6a-de33-4e6c-8219-1eab9727ae94",
  • "operatingDeviceId": "558aef6a-de33-4e6c-8219-1eab9727ae94",
  • "userId": "558aef6a-de33-4e6c-8219-1eab9727ae94",
  • "granted": true
}

LockingDeviceAuditLogEntryReceivedV2 Webhook

Triggered when the platform receives a locking device audit log entry from a locking device.

Audit log entries are logged for all operations that clients execute on locking devices.

Log entries are delivered to the platform by operating devices and gateway devices.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "LockingDeviceAuditLogEntryReceivedV2"

Type of the event

logEntryId
required
string <uuid>

Identifier of the log entry

logEntryEventName
required
string

Name of the operation executed by the operating device

Technically this maps to the name of the performed ThingRPC conversation.

logEntryDatetime
required
string <date-time>

Datetime (ISO 8601) the event occurred at in the locking device

logEntrySequenceNumber
required
integer

Running number that is incremented every time a new log entry occurs in the locking device

lockingDeviceId
required
string <uuid>

Identifier of the locking device that the log entry originates from

required
any

Client that operated the locking device

granted
required
boolean

Indicates that the operating device that attempted to execute the operation had a valid operating key with sufficient permissions and that the operation was therefore permitted

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "LockingDeviceAuditLogEntryReceivedV2",
  • "logEntryId": "558aef6a-de33-4e6c-8219-1eab9727ae94",
  • "logEntryEventName": "unlock",
  • "logEntryDatetime": "2019-08-24T14:15:22Z",
  • "logEntrySequenceNumber": 101,
  • "lockingDeviceId": "558aef6a-de33-4e6c-8219-1eab9727ae94",
  • "client": {
    },
  • "granted": true
}

UnauthorizedLockingDeviceAccessDetected Webhook

Triggered when potentially unauthorized access to a locking device has been detected.

Limitation: Technically this event is triggered when the platform receives a locking device audit log entry for which there is no matching operating device, for example if the locking device has already been deleted. Due to this check being evaluated only when the audit log entries are eventually received by the platform, it is also possible that when the locking device was operated the operating device still existed and had a valid permission to operate the locking device.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "UnauthorizedLockingDeviceAccessDetected"

Type of the event

logEntryId
required
string <uuid>

Identifier of the log entry

logEntryEventName
required
string

Name of the operation executed by the operating device

Technically this maps to the name of the performed ThingRPC conversation.

logEntryDatetime
required
string <date-time>

Datetime (ISO 8601) the event occurred at in the locking device

logEntrySequenceNumber
required
integer

Running number that is incremented every time a new log entry occurs in the locking device

lockingDeviceId
required
string <uuid>

Identifier of the locking device that the log entry originates from

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "UnauthorizedLockingDeviceAccessDetected",
  • "logEntryId": "558aef6a-de33-4e6c-8219-1eab9727ae94",
  • "logEntryEventName": "unlock",
  • "logEntryDatetime": "2019-08-24T14:15:22Z",
  • "logEntrySequenceNumber": 101,
  • "lockingDeviceId": "558aef6a-de33-4e6c-8219-1eab9727ae94"
}

LockingDeviceCertificateEligibleForReKeying Webhook

Triggered when a locking device certificate becomes eligible for re-keying.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "LockingDeviceCertificateEligibleForReKeying"

Type of the event

lockingDeviceId
required
string <uuid>

Identifier of the locking device that is eligible for re-keying

certificateProfile
required
string (CertificateProfile)
Enum: "OPERATIONAL" "MANUFACTURING"

Profile of the locking device certificate

Each locking device has two key pairs and certificates: operational and manufacturing.

certificateExpirationDatetime
required
string <date-time>

Datetime (ISO 8601) the current certificate will expire if re-keying is not completed

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "LockingDeviceCertificateEligibleForReKeying",
  • "lockingDeviceId": "688674e3-f5bd-489e-b7c0-1970d5d96020",
  • "certificateProfile": "OPERATIONAL",
  • "certificateExpirationDatetime": "2019-08-24T14:15:22Z"
}

LockingDeviceCertificateSigningRequestCreated Webhook

Triggered when an operating device has initiated re-keying process for a locking device and the locking device has successfully created a certificate signing request for its new key pair.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "LockingDeviceCertificateSigningRequestCreated"

Type of the event

lockingDeviceId
required
string <uuid>

Identifier of the locking device that the certificate signing request was created for

certificateProfile
required
string (CertificateProfile)
Enum: "OPERATIONAL" "MANUFACTURING"

Profile of the locking device certificate

Each locking device has two key pairs and certificates: operational and manufacturing.

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "LockingDeviceCertificateSigningRequestCreated",
  • "lockingDeviceId": "688674e3-f5bd-489e-b7c0-1970d5d96020",
  • "certificateProfile": "OPERATIONAL"
}

LockingDeviceCertificateIssued Webhook

Triggered when a new certificate has been issued for a locking device as part of the re-keying process. After this an operating device can complete the re-keying process by delivering the newly issued certificate to the locking device.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "LockingDeviceCertificateIssued"

Type of the event

lockingDeviceId
required
string <uuid>

Identifier of the locking device that the certificate is issued for

certificateProfile
required
string (CertificateProfile)
Enum: "OPERATIONAL" "MANUFACTURING"

Profile of the locking device certificate

Each locking device has two key pairs and certificates: operational and manufacturing.

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "LockingDeviceCertificateIssued",
  • "lockingDeviceId": "688674e3-f5bd-489e-b7c0-1970d5d96020",
  • "certificateProfile": "OPERATIONAL"
}

LockingDeviceCertificateReKeyingCompleted Webhook

Triggered when re-keying process is completed for a locking device.

Re-keying process is considered complete when the operating device delivers the new certificate for the locking device and the locking device successfully installs the certificate.

Note: This event is triggered only after the platform has received a locking device system log entry that contains information about the re-keying process being complete.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "LockingDeviceCertificateReKeyingCompleted"

Type of the event

lockingDeviceId
required
string <uuid>

Identifier of the locking device that completed the re-keying process

certificateProfile
required
string (CertificateProfile)
Enum: "OPERATIONAL" "MANUFACTURING"

Profile of the locking device certificate

Each locking device has two key pairs and certificates: operational and manufacturing.

certificateExpirationDatetime
required
string <date-time>

Datetime (ISO 8601) the new certificate will expire

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "LockingDeviceCertificateReKeyingCompleted",
  • "lockingDeviceId": "688674e3-f5bd-489e-b7c0-1970d5d96020",
  • "certificateProfile": "OPERATIONAL",
  • "certificateExpirationDatetime": "2019-08-24T14:15:22Z"
}

GatewayDeviceActivated Webhook

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Triggered when a gateway device has activated itself.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "GatewayDeviceActivated"

Type of the event

gatewayDeviceId
required
string <uuid>

Identifier of the gateway device

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "GatewayDeviceActivated",
  • "gatewayDeviceId": "c78afb03-a06e-4da9-afca-edce82ffad9f"
}

RemoteCommandAcknowledged Webhook

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Triggered when a remote command has been acknowledged by a gateway device.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "RemoteCommandAcknowledged"

Type of the event

remoteCommandId
required
string <uuid>

Identifier of the remote command

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "RemoteCommandAcknowledged",
  • "remoteCommandId": "de037108-e305-4e69-9be2-91260ca712df"
}

GatewayDeviceSystemLogEntryReceived Webhook

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Triggered when the platform receives a system log entry from a gateway device.

System log entries are logged for internal events of a gateway device, such as the gateway device having booted up.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "GatewayDeviceSystemLogEntryReceived"

Type of the event

gatewayDeviceId
required
string <uuid>

Identifier of the gateway device that the log entry originates from

required
any (GatewayDeviceSystemLogEntry)

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "GatewayDeviceSystemLogEntryReceived",
  • "gatewayDeviceId": "c78afb03-a06e-4da9-afca-edce82ffad9f",
  • "logEntry": {
    }
}

GatewayDeviceAuditLogEntryReceived Webhook

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Triggered when the platform receives an audit log entry from a gateway device.

Audit log entries are logged for each ThingRPC conversation that the gateway device has executed on a locking device.

Request Body schema: application/json
required
eventId
required
string <uuid>

Identifier of the event

eventSystemId
required
string <uuid>

Identifier of the system that the event occurred in

eventType
required
string
Value: "GatewayDeviceAuditLogEntryReceived"

Type of the event

gatewayDeviceId
required
string <uuid>

Identifier of the gateway device that the log entry originates from

required
object (GatewayDeviceAuditLogEntry)

Responses

Request samples

Content type
application/json
{
  • "eventId": "f668f9e9-3356-4354-93b0-350a3d533308",
  • "eventSystemId": "05fb1fa6-5826-4da1-b334-5c1613c5e8f1",
  • "eventType": "GatewayDeviceAuditLogEntryReceived",
  • "gatewayDeviceId": "c78afb03-a06e-4da9-afca-edce82ffad9f",
  • "logEntry": {
    }
}

Development Support

This sections contains functionalities for testing and development.

Note: These are not available in production.

Initiate re-key for a locking device

Experimental

This functionality is experimental, which means that it can be subject to backwards incompatible changes without a major version number increase. It is not recommended to use this functionality in production environments.

Initiates the re-key process for the operational certificate of the given locking device, even if its certificate is not expiring. This allows easier testing of the re-key functionalities for integrators.

Note: This endpoint is not available in production.

Authorizations:
(ApiKeyBearerToken)
path Parameters
locking-device-id
required
string <uuid> (ResourceId)
Example: 558aef6a-de33-4e6c-8219-1eab9727ae94

Identifier of the locking device for which the re-key will be initiated.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "about:blank",
  • "title": "Forbidden",
  • "status": 403,
  • "detail": "This action is not available in this environment.",
  • "instance": "http://example.com"
}

Changelog

Version 2.13 (May 7th 2025)

Version 2.12 (May 6th 2025)

  • Added format property for operating device invitation requests and all delivery mechanisms to support generating invitations in different formats.

Version 2.11 (April 15th 2025)

  • Added experimental gateway device log entry type NETWORK_CHANGED.
  • This new entry type replaces the NETWORK_CONNECTION_PROVIDER_CHANGED entry type. As such, the old entry type has been removed.

Version 2.10 (April 10th 2025)

  • Added new device information fields (hardware model, hardware version & firmware version) to the Get Gateway Device & Get Gateway Devices endpoints.

Version 2.9 (January 24th 2025)

Version 2.8 (December 18th 2024)

Version 2.7 (December 4th 2024)

Version 2.6 (October 21st 2024)

  • Added experimental gateway device log entry type NETWORK_CONNECTION_PROVIDER_CHANGED.

Version 2.5 (September 23rd 2024)

  • Changes to the experimental gateway device system log entries.

Version 2.4 (August 21st 2024)

Version 2.3 (August 8th 2024)

Version 2.2 (August 6th 2024)

Version 2.1 (June 19th 2024)