Adding users to a site

When adding users to a site, it is important to keep a few things in mind, such as whether they have a profile or not, and which user role you want to assign to them. This will determine how they can use the platform and which actions they can take.

1. Users with or without profile

Two types of users can be added to a site: with or without a profile. Users without a profile do not have an email address linked to them. This means they do not log in via the API and cannot use features such as remote opening. The only access method available for these users is a physical Tag.

Users with a profile have an email address linked to them and can therefore log in via the API. This also means they can make use of all the features available in the app, including all access methods: Tag, PIN, remote opening and Digital Key.

The image below shows how to add a user without a profile. If you want to add a user with a profile, then you must add the following to the body: {user_email}. This will cause an invitation email to be sent out to the user, so they can complete their profile.

A. Create a POST request to {{url}}/v1.1/sites/{site_id}/users. In the body provide the information like shown above. A user has a certain role, to see the available roles on your site do GET {{url}}/v1.1/sites/{site_id}/roles. You can provide a Tag for the user to be associated with by filling in the tag ID. This is optional, a tag can also be added later to a user.
On success the endpoint will return the details of the user that was added.

2. User roles: hierarchical and non-hierarchical

Each user role comes with a different set of permissions, determining what the user can view and do in the platform. The first step is to fetch the full list of roles that can be assigned to a user. You must do that in order to get the corresponding code ID for that user role, which you will need when assigning roles.

There are two types of user roles: hierarchical and non-hierarchical. With hierarchical roles, each role inherits all the rights from the role below them. There are four hierarchical roles (in order from the lowest to the highest level of hierarchy): Site Guest, Site User, Site Super User and Site Admin. Even though on the UI side, there is a role called Site Owner, this is not a role on the API level. Instead, the owner of a site gets assigned the role of Site Admin and is given a flag to identify this user as the owner of the site. Keep in mind that each user role inherits all the rights from the role below them, hierarchically speaking. If you want to learn more about each site user role and their respective role IDs and rights, please click the button below:

Site user roles

As for the non-hierarchical roles, they are not associated with one another in terms of inheriting rights, but rather each role is separate. There are currently three non-hierarchical roles: Pod member, Site Remote Office Mode User and Site Mobile User. As these roles are non-hierarchical, they can only be assigned to users who already have a hierarchical role assigned to them.

The Pod member role is attributed to users who become members of a Pod. Pay attention to the fact that Pod member is not an assignable role (more on that in the next section).

The Site Remote Office Mode User role is assigned to users who can have the rights to enable the Remote Office Mode. The Remote Office Mode is a status that can be enabled on a lock to keep it constantly open for a given time frame. Even if the door is shut, the lock won’t close and users won’t require a credential to open it (given it is within the predefined time frame).

The Site Mobile User role is the most widely used non-hierarchical role and it is assigned to users who are on the Mobile version of the SALTO KS application. This is an important role because it is the one that defines Remote Opening permissions.

3. User roles: assignable and non-assignable

It’s also important to keep in mind that some roles are assignable and some are not.

There are two roles that are currently non-assignable:

Site Guest: this role gets assigned automatically when a Guest is added to a Pod via an Access Code
Pod Member: this role can't be assigned manually, but it gets assigned automatically when a user is added to a Pod. It gets removed when a user gets removed from a Pod