Skip to main content

Groups

Groups are sets of members that have access to a set of resources (e.g. doors or elevators) that share the same restrictions. They are defined in the admin dashboard.

The advantage of using groups is the ease of managing members that have the same access points and the same restrictions applied to them—geofence, primary device, by reader, or by time.

Each group must have a name and a description. Group restrictions affect all group members. However, if a member is in multiple groups and any group permits access, the user is considered authorized.

Groups can be associated with doors or elevators (through elevator stops).

To create a group, use a curl call. You will need the id of your locks or elevators in each case.

curl 'https://api.kisi.io/groups' \
-H 'Accept: application/json' \
-H 'Authorization: KISI-LOGIN {authentication_token}' \
-H 'Content-Type: application/json' \
--data-raw '{"group":{"name":"New group","description":"My new group","locks":[{"id":16721}],"elevator_stops":[{"id":429},{"id":430}]}}'

Once you create the group, you can add users to the group by creating shares.

Check out all the Group endpoints you can use at Groups.

Restrictions#

To have more control over how and when users can access places, Kisi offers some configurable restrictions that can be applied to a group by location, time, or device.

Geofence restrictions#

The geofence restriction uses the GPS (location) of the user's mobile phone to determine proximity to a door.

With Kisi, if the geofencing feature is enabled, the default allowed distance is within 300 meters (or .2 miles) from the door. This means that if an employee normally uses the remote unlock button to get into the office every day, there is no risk that he or she can accidentally unlock the door from their home or in transit. Geofencing ensures that users must be in the vicinity of the building.

For group or place admins, enabling the Geofencing feature on Kisi is as simple as toggling one button in the settings section of the dashboard.

The feature can also be set for a specific group and even a specific lock. For example, if you have a facility with Kisi installed on several doors but only need to set the geofencing feature for one of them, the administrator can choose which doors or places in their network are restricted with a geofence. Another scenario is a facility with high traffic and multiple temporary visitors (like contractors or maintenance workers) that needs to grant basic access to many people. They can use Geofencing to ensure the busy entryway does not get accidentally triggered by anyone.

Users will have to enable Kisi to access their phone's location (or whatever device they use) to ensure they gain proper access within the geofence. If their location settings are not correct, users trying to access a door with the geofence enabled may receive an "Unlock Error". When users receive an unlock error, it is due to one of three factors. Either their location services are not enabled, they have not shared their location with Kisi, or they are too far from the office.

Reader restrictions#

The reader restriction uses the Bluetooth chip of the mobile phone (and the reader) to know if the user is next to the door or not with a precision of approximately 5 meters.

If the Kisi reader restriction is enabled, the user needs to be within range of a Kisi reader to unlock. This means that if employees normally use the remote unlock button to get into the office every day, there is no risk that they can accidentally unlock the door from their home or in transit. It works the same way as Geofencing but with significantly higher accuracy.

For the admins of a group or place, enabling the reader restriction feature on Kisi is as simple as toggling one button in the Settings section of the dashboard.

As with geofence restriction, the reader restriction can also be set for a specific group or lock and users will have to enable Kisi to access their phone's location (or whatever device they use) to ensure they gain proper access within the reader proximity. They may also receive an "Unlock Error" if their location settings are not correct, meaning that either the location services are not enabled, they have not shared their location with Kisi, or they are too far from the office.

Primary device restrictions#

Every Kisi user has a primary device they use to access a space. The primary device restriction allows the user to perform unlocks from one specific device, be it a smartphone or tablet. For example, if an employee normally opens the office door with an iPhone, and then one day decides to log in to Kisi from a Samsung tablet, the unlock will be prohibited. This restriction allows all unlocks to be traced back to one device for a particular user, making audit trails easier to review for administrators and encouraging users to update their primary device when they get a new phone.

To create geofence, primary device or reader restrictions through the API, you only need to set them to true:

curl 'https://api.kisi.io/groups/{group_id}' \
-H 'Accept: application/json' \
-H 'Authorization: KISI-LOGIN {authentication_token}' \
-H 'Content-Type: application/json' \
--data-raw '{"group":{"geofence_restriction_enabled":true,"primary_device_restriction_enabled":true,"reader_restriction_enabled":true}}'

Time restrictions#

Time restrictions allow admins to set a specific window for users to access a space. This is particularly useful for spaces that have strict hours, conference room bookings, or even weekend emergencies. For example, the admin can set a group of people to have access to a specific space from 9 AM to 6 PM only. If they attempt to unlock the door outside of those allowed time frames, they will be denied access. This allows admins to be flexible when specific people or teams need access in emergencies or to enforce strict hours.

Create a time restriction:

curl 'https://api.kisi.io/schedules' \
-H 'Accept: application/json' \
-H 'Authorization: KISI-LOGIN {authentication_token}' \
-H 'Content-Type: application/json' \
--data-raw '{"schedule":{"type":"single_event","starts_at":"2021-05-04T15:43:00.000+00:00","ends_at":"2021-05-04T22:43:00.000+00:00","consequence":"allow","scheduleable_type":"Group","scheduleable_id":25305}}'

The scheduleable_id is the group_id.