Skip to main content

Assign access rights

info

The term role assignment in the Kisi API is equivalent with the term access right in the web UI.

Send a POST request to the Create role assignment endpoint. Based on which level you want to add a new access right (i.e. role assignment), find the examples and responses shown on the tabs below.

curl --request POST \
  --url https://api.kisi.io/role_assignments \
  --header 'Authorization: KISI-LOGIN <API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "role_assignment": {
    "user_id": 0,
    "role_id": "string",
    "group_id": 0,
    "valid_from": "2023-05-24T14:15:22Z",
    "valid_until": "2023-05-25T14:15:22Z"
  }
}'
  • user_id - the id of the user you're assigning the role to
  • role_id - the id of the role you're assigning. The parameter may have one of the following values:
    • group_manager
    • group_basic (Note: This is the most common use case. Use this role assignment to grant users access to unlock a set of doors.)
  • group_id - the id of the group where the user should have the role. You can find this value at the very end of the group's URL in the web UI. For example, 45274 is the group ID of https://web.kisi.io/organization/3289/groups/45274
  • valid_from - the date and time when the role assignment starts to be valid
  • valid_until - the date and time when the role assignment ceases to be valid
tip

For an exhaustive list of all Kisi roles and the permissions associated with them, refer to our Roles page.

Response

If your request was successful, you'll receive a 200 OK response, along the created role assignment object. It contains, among other things, the following parameters:

{
  "id": 0,
  "role_id": "string",
  "type": "group",
  "group_id": 0
}
  • id - the role assignment id
  • type - the scope of the role assignment, in this case group
info

There can be only one organization owner in Kisi, therefore currently it's not possible to assign an owner role. A user can't have more than one role assignment in the same place or group, but can have more than one place- or group-level roles for different places and groups. (e.g. place access manager for Place A and place administrator for Place B).

Roles and restrictions​

In Kisi, some restrictions can be applied to both groups and doors, some of them only to groups.

If you share access via assigning roles, that will grant the user access to an entire place/organization. In this case, only restrictions set on doors will need to be complied with for unlocks, i.e. geofence, Kisi Reader, and time restrictions. This means, restrictions that only apply to groups can't be applied to individual users, only to entire groups.

Example: If you share access via assigning roles, you won't be able to disable the App access restriction for individual users, but only for entire groups.

If you want to enable/disable group-only restrictions, make sure you share access via groups instead.

Role vs role assignment​

In the Kisi API terminology, we differentiate between role and role assignment. While the role refers to the actual role, a role assignment is a connection between a user, a role, and a scope, i.e. organization, place, or group.

Example:

  • Role: place administrator
  • Role assignment: Example User + place administrator + Place A