# Granting user access via the Connect API
> How to grant users access with the Salto KS Connect API.


## Overview

This document provides information on how to grant access to users via the [Salto KS Connect API](/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](/ks/connect-api/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](https://developer.saltosystems.com/ks/connect-api/reference/#/Sites/get_v1_2_sites)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/Locks/patch_v1_2_sites__site_id__locks__id__tag_registration)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/Tags/get_v1_2_sites__site_id__tags)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/SiteUsers/post_v1_2_sites__site_id__users)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/Roles/get_v1_2_sites__site_id__roles)).

* 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](https://developer.saltosystems.com/ks/connect-api/reference/#/SiteUsers/patch_v1_2_sites__site_id__users__site_user_id_)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroups/post_v1_2_sites__site_id__access_groups)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroups/patch_v1_2_sites__site_id__access_groups__access_group_id_)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroups/delete_v1_2_sites__site_id__access_groups__access_group_id_)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroupsLocks/post_v1_2_sites__site_id__access_groups__access_group_id__locks)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/Locks/get_v1_2_sites__site_id__locks)).

* 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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroupsLocks/patch_v1_2_sites__site_id__access_groups__access_group_id__locks)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroupsLocks/delete_v1_2_sites__site_id__access_groups__access_group_id__locks__lock_id_)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroupsTimeSchedules/post_v1_1_sites__site_id__access_groups__access_group_id__time_schedules)).
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](/ks/guides/granting-user-access-ks#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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroupsTimeSchedules/patch_v1_1_sites__site_id__access_groups__access_group_id__time_schedules__time_schedule_id_)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroupsTimeSchedules/delete_v1_1_sites__site_id__access_groups__access_group_id__time_schedules__time_schedule_id_)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroupUsers/post_v1_2_sites__site_id__access_groups__access_group_id__users)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/SiteUsers/get_v1_2_sites__site_id__users)).

* 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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroupUsers/patch_v1_2_sites__site_id__access_groups__access_group_id__users)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/AccessGroupUsers/delete_v1_2_sites__site_id__access_groups__access_group_id__users__user_id_)).
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](https://developer.saltosystems.com/ks/connect-api/reference/#/Locks/patch_v1_2_sites__site_id__locks__id__locking)).
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.

{{% info-panel %}}
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](https://support.saltosystems.com/ks/hardware/iqs-and-repeaters/#how-do-i-generate-a-code-from-an-iq).
{{% /info-panel %}}

## 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.

{{% collapsible summary="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
}
```

{{% /collapsible %}}

### 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.

{{% collapsible summary="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"
}
```

{{% /collapsible %}}

### 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.

{{% collapsible summary="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"
}
```

{{% /collapsible %}}

### 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.

{{% collapsible summary="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"
}
```

{{% /collapsible %}}