Abloy BEAT Administration API (0.9.0)

The basic workflow to get started is the following:

1. Invite users in to the system.
2. Add locks in to the system.
3. Give a user permissions to operate certain lock in the system.

Also check how to delete users and revoke permissions.

The API version needs to be passed in the request Accept header using the vendor-specific media type application/vnd.assaabloy.abloybeat.administration-0.9+json.

This section describes the differences between the 0.9 and 2.0 versions of the Administration API. Use this guide during the migration process. Since there are significant differences between the two versions, it is recommended to manually check every place where the API is directly invoked.

URL changes

The 2.0 version of the API lives under a different URL.

The URL changes for the staging are the following:

• 0.9 - https://apigw.sampo-staging.aah.assaabloy.net/administration/
• 2.0 - https://eu-staging-api.keyless.assaabloy.com/administration/

The URL changes for the production are the following:

• 0.9 - https://eu-apigw.abloybeat.api.assaabloy.com/administration/
• 2.0 - https://eu-api.keyless.assaabloy.com/administration/

Media Type changes

The API continues to use media types for content negotiation in version 2.0. Every request must provide a specific media type in the Accept header, which is also the Content-Type header of the response on a successful execution. Starting from API 2.0, only the major version is used in content negotiation. Also notice that the "abloybeat" is changed to "keyless" to be aligned with the new domain name of the API.

The Accept header changes are the following:

• 0.9 - application/vnd.assaabloy.abloybeat.administration-0.9+json
• 2.0 - application/vnd.assaabloy.keyless.administration-2+json

Introducing API keys and rate limiting

API keys are a new concept, and it is recommended to check out the relevant section of the 2.0 documentation.

In short:

• It is required to have an API key to access to 2.0 version of the API. This should be provided to you by your ASSA ABLOY contact person.
• Provide the API key in the X-Api-Key header for every request.
• If the key is invalid, the request will return 403 Forbidden.
• If a rate limit is reached, the request will return 429 Too Many Requests. In that case the request should be retried after some delay.

Prepare the integrated applications for reaching the rate limit and make sure it is handled gracefully.

Changes to users and the registration process

In 0.9 the person, who can receive permissions, and his/her device, that can operate locks based on those permissions, are both represented by the User entity.

In 2.0 these two concepts are split into two different entities. User represent the person, who can receive permissions. Operating Device represent the mobile device that can interact with the lock.

This means changes in the registration process.

In 0.9 a user can be invited by the POST /invitation endpoint. This takes care of both creating the user account and registering the mobile device. The user credentials were returned in a callback.

In 2.0 this is a two-step process.

• First a user needs to be created with POST /user. This will return the user's credentials.
• Then an operating device needs to be invited for the user with POST /operating-device-invitation.

This process is described in more detail later in this guide.

For admin users who would like to access the API but will not operate the locks, it is enough to create the user. Inviting an operating device is not necessary.

Changes per endpoint

GET /lock

In 2.0 this endpoint maps to GET /locking-device

Notable changes:

• The paging style has changed to a token based paging. Page, size and sort query parameters are no longer acceptable and the response's paging information is also different. Consult the documentation of the new endpoint for the changes.
• The claimed query parameter is replaced by claiming-status, and it is not a required parameter anymore. The claiming status also now appears in the response in a field named claimingStatus.
• lockingDeviceSerialNumber query parameter changes to serial-number.
• lockingDeviceSerialNumber field in the returned entity changes to serialNumber.

GET /lock/{id}

In 2.0, this endpoint maps to GET /locking-device/{locking-device-id}

POST /lock

In 2.0, this endpoint maps to POST /locking-device

PUT /lock/{id}

In 2.0, this endpoint maps to PATCH /locking-device/{locking-device-id}

The same thing could be achieved in both cases: updating the name of the locking device. However, the PATCH syntax is radically different. Refer to the API 2.0 docs on how to use it.

POST /permission

In 2.0, this endpoint maps to POST /permission

In 2.0 the structure of the request body has been redesigned. Unlike in 0.9, the request content type is always application/json. Every request body contains the fields of userId, lockingDeviceId (lockId in 0.9), operationType (type in 0.9) and the permissionType. Permission type is a new field introduced in 2.0. It determines if the created permission is single interval, recurring or multiple interval. Based on the permission type, there will be additional fields in the request body.

• On permissionType=SINGLE_INTERVAL start and end fields will be required, which map to the start and end fields of the 0.9 request. However, in 0.9 they were not required.
• On permissionType=RECURRING start, end, weekday and intervals fields will be available, from which intervals will be required. These map to the fields of the recurrence object in the 0.9 request body.
• On permissionType=MULTIPLE_INTERVALS the intervals fields will be required. This maps to the interval field of the 0.9 request body with content type application/multiple.intervals+json.

PUT /permission/{id}

In 2.0, this endpoint maps to PUT /permission/{permission-id}

The changes to this endpoint are identical to the changes described under POST /permission

DELETE /permission/{id}

In 2.0, this endpoint maps to DELETE /permission/{permission-id}

POST /invitation

In 2.0, there is no direct mapping for this endpoint. It is required to call two separate endpoints in correct order to achieve the same result.

First call POST /user where the role field maps to the role field of POST /invitation from 0.9.

Then call POST /operating-device-invitation. The userId field maps to the id field from the response of the previous POST /user.

The validityDuration field maps to the validFor field of POST /invitation from 0.9.

The deliveryMechanism field partially maps to the contact/type field of POST /invitation from 0.9. It also introduces new fields to the request body based on its value.

• The deliveryMechanism=SMS means the same as contact/type=PHONE in POST /invitation in 0.9. In this case, the required phoneNumber field maps to the contact/value of POST /invitation from 0.9.
• The deliveryMechanism=EMAIL means the same as contact/type=EMAIL in POST /invitation in 0.9. In this case, the required emailAddress field maps to the contact/value of POST /invitation from 0.9.
• The deliveryMechanism=NONE will map the whole request to the POST /invitation-code from 0.9

The id field in the response of POST /operating-device-invitation maps to the id field in the response of POST /invitation

The expirationDatetime field in the response of POST /operating-device-invitation maps to the expiresAt field in the response of POST /invitation

POST /invitation-code

In 2.0, there is no direct mapping for this endpoint. It is required to call two separate endpoints in correct order to achieve the same result.

First call POST /user where the role field maps to the role field of POST /invitation-code from 0.9.

Then call POST /operating-device-invitation. The userId field maps to the id field from the response of the previous POST /user.

The validityDuration field maps to the validFor field of POST /invitation from 0.9.

The deliveryMechanism filed has to be set to NONE: deliveryMechanism=NONE

In this case, the fields in the response of POST /operating-device-invitation will directly map to the fields in the response of POST /invitation-code from 0.9.

GET /user

In 2.0, this endpoint maps to GET /user

DELETE /user/{id}

In 2.0, this endpoint maps to DELETE /user/{user-id}

POST /login

In 2.0, this endpoint maps to POST /login/

To add locks to the system one must first create an unclaimed lock. Unclaimed locks are not yet connected to physical locks. To make this connection, you have to register the lock with the Abloy BEAT mobile app. Registering an unclaimed lock claims the lock for the account being used.

Permissions are used to manage users' access to locks.

To add users to the system they always need to be invited. The invited user will receive an invitation code. The invited user then needs to activate his mobile device from the Abloy BEAT mobile app.

An activated user can be also deleted, which will remove all accesses the user has, and prevent further accesses from being granted.

Users need to be authenticated to be able to call most Abloy BEAT APIs. The login will return an authorization token which must be passed as a request header in every request to endpoints that require authorization.