Granting user access via the Connect API

Overview

This document provides information on how to grant access to users via the Salto KS Connect API. Granting user access is done by creating an access group in a site, followed by adding three key components: users, locks, and time schedules. This determines which users should have access to which locks of a site, during a given timeframe.

Setting up a Salto KS site is carried out by installers, while granting user access is performed by a site owner and site admin. Note that when making API calls, a user must first get authenticated with the Salto KS Identity Provider. For more information on that, refer to the Salto KS Authentication page.

Creating a Salto KS site

In Salto KS, all access-related components are grouped together within a site, from users, to hardware, roles, and access rights. A site refers to a single physical location in the customer's installation, for instance, an office building or hotel property. In the case of Technology Partners integrating with the Salto KS Connect API, a site will be created for testing purposes by their local Salto Business Unit (BU) via the Larry Commissioning web application. Once the site is created, the BU will add the Partner to the site. The first recommended step is to make a first call to the API and ensure the steps carried out during the authentication phase were successful.

Make the first API call

Make the first call to the API by sending a GET request to /v1.2/sites (check API reference). Set the Authorization header to Bearer ACCESS_TOKEN. This will automatically add the token previously obtained during the authentication phase to the request. This authorization key value should be present in all requests made to the API. Below, is an example of the API request.

bash
curl 'https://clp-accept-user.saltoks.com/v1.2/sites' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Adding tags to a site

One of the access credential types available to Salto KS users is the Salto tag. In order to be assigned to a user, a tag must first be added to the site that user is a part of. The process of adding tags to a site starts with selecting a lock, which must be part of that site, and setting it to registration mode. By doing so, the lock is turned into a registering device, allowing site admins to register and add new tags to the site by tapping them on this specific lock.

Adding tags

To set a lock to registration mode and activate it, make a PATCH request to /v1.2/sites/{site_id}/locks/{id}/tag_registration (check API reference). Replace the {site_id} with the ID of the site and replace the {id} with the ID of the lock that will be put in registration mode.
In the body of the request, set for how long the lock will remain in registration mode.
Once set to registration mode, tap the tag on the lock to add it to the site.

Getting list of tags

To confirm that the tags have been added to the site after presenting them to the lock in registration mode, make a GET request to /v1.2/sites/{site_id}/tags (check API reference). Replace the {site_id} with the ID of the site. This request will return a list of all the tags belonging to that site.

Adding users to a site

Before being added to an access group, users must first be added to the site.

Adding users

Make a POST request to /v1.2/sites/{site_id}/users (check API reference). Replace the {site_id} with the ID of the site the user is being added to.
In the body of the request, provide the following information about the user: first name, last name, email, role ID, and the alias. To get a list of the available site roles and their corresponding IDs, make a GET request to /v1.2/sites/{site_id}/roles (check API reference).
In the body of the request, provide the ID of the tag that will be assigned to the user. A tag can be assigned to a user via the above POST call when adding the user, or later via a PATCH call to /v1.2/sites/{site_id}/users/{site_user_id} (check API reference). The PATCH call updates the information of an existing user in the site. Replace the {site_user_id} with the ID of the user.
After sending the POST request, a 200-OK response should be expected.

Creating, updating or deleting an access group

In Salto KS, access is granted to users of a site by adding them to an access group. An access group defines which users have access to which locks for a given timeframe. This is done by adding a list of users and a list of locks to an access group, as well as determining the time schedule for which this access should be valid.

Creating, updating or deleting an access group

To create an access group, make a POST request to /v1.2/sites/{site_id}/access_groups (check API reference). Replace the {site_id} with the ID of the site that the access group is being added to.
In the body of the request, specify the customer_reference, which will be set as the name of the access group.
After sending the POST request, a 200-OK response should be expected with the ID of the newly created access group.
To update the access group after it is created, make a PATCH request to /v1.2/sites/{site_id}/access_groups/{access_group_id} (check API reference). Include the ID of the site and the ID of the access group.
To delete the access group, make a DELETE request to /v1.2/sites/{site_id}/access_groups/{access_group_id} (check API reference). Include the ID of the site and the ID of the access group.

Adding, updating or deleting a lock from an access group

To add a lock to an access group, make a POST request to /v1.2/sites/{site_id}/access_groups/{access_group_id}/locks (check API reference). Replace the {site_id} and {access_group_id} with the IDs of the site and access group that the lock is being added to.
In the body of the request, provide the ID of the lock that is being added to the access group. To get the list of locks of a site and their corresponding IDs, make a GET request to /v1.2/sites/{site_id}/locks (check API reference).
To update the list of locks in an access group, make a PATCH request to /v1.2/sites/{site_id}/access_groups/{access_group_id}/locks (check API reference). Include the ID of the site and the ID of the access group.
To delete a lock from an access group, make a DELETE request to /v1.2/sites/{site_id}/access_groups/{access_group_id}/locks/{lock_id} (check API reference). Include the ID of the site, the ID of the access group and the ID of the lock.

Adding, updating or deleting a time schedule from an access group

To add a time schedule to an access group, make a POST request to /v1.1/sites/{site_id}/access_groups/{access_group_id}/time_schedules (check API reference). Replace the {site_id} and {access_group_id} with the IDs of the site and access group that the time schedule is being added to.
In the body of the request, provide the details of the time schedule. For more information, check the section Configuring a time schedule for an access group at the end of this Developer Guide.
To update the time schedule of an access group, make a PATCH request to /v1.1/sites/{site_id}/access_groups/{access_group_id}/time_schedules/{time_schedule_id} (check API reference). Include the ID of the site, the ID of the access group and the ID of the time schedule.
To delete a time schedule from an access group, make a DELETE request to /v1.1/sites/{site_id}/access_groups/{access_group_id}/time_schedules/{time_schedule_id} (check API reference). Include the ID of the site, the ID of the access group and the ID of the time schedule.

Adding, updating or deleting a user from an access group

To add a user to an access group, make a POST request to /v1.2/sites/{site_id}/access_groups/{access_group_id}/users (check API reference). Replace the {site_id} and {access_group_id} with the IDs of the site and access group that the user is being added to.
In the body of the request, provide the ID of the user that is being added to the access group. To get the list of users of a site and their corresponding IDs, make a GET request to /v1.2/sites/{site_id}/users (check API reference).
To update the list of users of an access group, make a PATCH request to /v1.2/sites/{site_id}/access_groups/{access_group_id}/users (check API reference). Include the ID of the site and the ID of the access group.
To delete a user from an access group, make a DELETE request to /v1.2/sites/{site_id}/access_groups/{access_group_id}/users/{user_id} (check API reference). Include the ID of the site, the ID of the access group and the ID of the user.

With the above steps complete, users will have access to the locks added to the access group, during the time schedule that was configured.

Performing a remote opening

Once the access group has been fully configured, you can start performing remote openings on Salto KS locks via the API.

Make a PATCH request to /v1.2/sites/{site_id}/locks/{id}/locking (check API reference). Replace the {site_id} with the ID of the site and replace the {id} with the ID of the lock that will be opened.
In the body of the request, set locked_state to unlocked.
After sending the PATCH request, a 200-OK response should be expected, and the lock should open within seconds.

For locks attached to IQs that have not yet been updated and still require OTP, make sure to include the OTP in the body of the request of the PATCH call. For more information on generating an OTP for an IQ, check this page.

Configuring a time schedule for an access group

When configuring a time schedule for an access group, it is important to understand the fields from the request body and the parameters that must be set for configuring a time schedule. Below is the request body of an API call to configure a time schedule:

json
{
  "monday": true,
  "tuesday": true,
  "wednesday": true,
  "thursday": true,
  "friday": true,
  "saturday": true,
  "sunday": true,
  "start_time": "08:00:00",
  "end_time": "18:00:00",
  "start_date": "2020-07-08T10:00:00.000",
  "end_date": "2020-07-08T16:00:00.000"
}

The monday to sunday fields correspond to the days of the week in which the time schedule should be either active or inactive, with true setting it to active and false to inactive.

The start_time and end_time fields indicate the timeframe of the exact hours in a day within which the user will have access. This means that for each day of the week that has been set to true, the user's access will start from the time indicated in start_time and automatically end at the time indicated in end_time. Note that the start_time value must be a time before the end_time value.

The start_date and end_date fields indicate the period of calendar dates within which this time schedule will be active for. The value for these fields specifies both a date and a time. If no time is provided, then the API will consider these values as lasting the entire day, adding 00:00:00 and 23:59:59 to them, respectively. If time is provided, these will be considered as check-in and check-out values. It is also possible to set these fields to null, in which case the time schedule will start without delay and be active until deleted or changed. Note that the start_date value must be a date before the end_date value.

Examples of time schedule configurations

Click the arrows below to expand each example and view the configuration parameters.

Always

With this time schedule configuration, users will have access all the time, with no exceptions.

Always

json
{
  "monday": true,
  "tuesday": true,
  "wednesday": true,
  "thursday": true,
  "friday": true,
  "saturday": true,
  "sunday": true,
  "start_time": "00:00:00",
  "end_time": "23:59:59",
  "start_date": null,
  "end_date": null
}

Custom

With this time schedule configuration, users will have access from July 8 to July 20, from 8 AM to 6 PM, only during weekdays.

Custom

json
{
  "monday": true,
  "tuesday": true,
  "wednesday": true,
  "thursday": true,
  "friday": true,
  "saturday": false,
  "sunday": false,
  "start_time": "08:00:00",
  "end_time": "18:00:00",
  "start_date": "2020-07-08",
  "end_date": "2020-07-20"
}

Check-in & check-out (always)

With this time schedule configuration, users will have access from July 8 at 2 PM onward, until July 20 by 11 AM. Within that timeframe, they will have access all the time.

Check-in & check-out (always)

json
{
  "monday": true,
  "tuesday": true,
  "wednesday": true,
  "thursday": true,
  "friday": true,
  "saturday": true,
  "sunday": true,
  "start_time": "00:00:00",
  "end_time": "23:59:59",
  "start_date": "2020-07-08T14:00:00.000",
  "end_date": "2020-07-20T11:00:00.000"
}

Check-in & check-out (custom)

With this time schedule configuration, users will have access from July 8 to July 20, from 8 AM to 6 PM. However, on their check-in day (July 8), they will only have access from 2 PM to 6 PM, while on their check-out day (July 20), they will only have access from 8 AM to 11 AM, to accommodate usual check-in and check-out time restrictions.

Check-in & check-out (custom)

json
{
  "monday": true,
  "tuesday": true,
  "wednesday": true,
  "thursday": true,
  "friday": true,
  "saturday": true,
  "sunday": true,
  "start_time": "08:00:00",
  "end_time": "18:00:00",
  "start_date": "2020-07-08T14:00:00.000",
  "end_date": "2020-07-20T11:00:00.000"
}