User management scenarios

This guide will walk you through a few common scenarios around user management, useful for access control.

The scenarios are based on API calls, so it is more comfortable to read this while also having the API's OpenAPI docs at hand.

Users and user groups

Let's imagine we want to achieve the following setup, where User U3 is registered in the Logistics tenant, and belongs to the Technicians group of the Site 1 tenant.

We will assume that only the tenants already exist.

User creation

As we can see on the diagram, User U3 is registered in two tenants at a time. The order in which we register the user on the tenants does not matter.

Let's start with the Logistics tenant. This will be the first time that User U3 will be registered on the platform, so User U3's email should not exist in platform already.

POST
/tenants/:logisticsTenantId/users
{
    "email": "user.u3@example.com",
    "firstName": "User",
    "lastName":"U3"
}

Now the user is registered on the Logistics tenant only. It can login to platform with its credentials, but does not have any rights to see or do anything yet.

User U3 will be listed in the Logistics tenant:

GET
/tenants/:logisticsTenantId/users

[
    {
        id: ":userU3Id",
        email: "user.u3@example.com",
        firstName: "User",
        lastName: "U3",
    },
];

But it won't be listed in in the Site 1 tenant users:

GET
/tenants/:site1TenantId/users

[];

This prevents us from adding it to a user group on the Site 1 tenant.

So let's add User U3 to the Site 1 tenant as well:

POST
/tenants/:site1TenantId/users
{
    "email": "user.u3@example.com",
    "firstName": "User",
    "lastName":"U3"
}

Now User U3 will also appear in the users of the Site 1 tenant, with the same user ID as in the other tenant since we used the same email.

If we had provided a different email, another new user would have been created, with different login credentials.

If we had provided a different first or last name (but same email), the previous information on User U3 would have been kept.

User group creation

We want to User U3 to belong to the Technicians group in the Site 1 tenant.

Let's create the group on the tenant:

POST
/tenants/:site1TenantId/user-groups
{
  "name": "Technicians",
  "description": "These are the technicians on Site 1"
}

This will give us a new :techniciansGroupId. Then we can add our user to the group:

POST
/tenants/:site1TenantId/user-groups/:techniciansGroupId/users
{
    "userIds":[":userU3Id"]
}

We can see that User U3 appears in the user group's users:

GET
/tenants/:site1TenantId/user-groups/:techniciansGroupId/?loadUsers=true

{
    "id": ":techniciansGroupId",
    "name": "Technicians",
    "description": "These are the technicians on Site 1",
    "users": [
        {
            "id": ":userU3Id",
            "email": "user.u3@example.com",
            "firstName": "User",
            "lastName": "U3"
        }
    ]
}

Role assignments

Assuming we achieved the previous setup, we now want to enable the user to perform some actions on the Site 1 tenant.

The desired outcome would be this situation:

The users in the Technicians group should have two roles, one on the tenant, the other on one of the folders of the tenant.

Roles

To manipulate roles, we need to list them to know their IDs:

GET / roles;

[
    {
        "id": ":folderContributorRoleId",
        "name": "Folder Contributor",
        "permissionAssignments": [
         ...
        ]
    },
    {
        "id": ":deviceContributorRoleId",
        "name": "Device Contributor",
        "permissionAssignments": [
         ...
        ]
    }
]

Role assignment creation

We can create both role assignments at once.

POST
/tenants/:site1TenantId/user-groups/:techniciansGroupId/role-assignments

body:
[
    {
        "roleId": ":folderContributorRoleId",
        "identity": {
            "entityId": ":site1TenantId",
            "entityType": "Tenant"
        }
    },
    {
        "roleId": ":deviceContributorRoleId",
        "identity": {
            "entityId": ":BFolderId",
            "entityType": "Folder"
        }
    }
]

This way, for each role we can define in which identity scope the users will be able to perform their roles.

Now we have also achieved to create the second situation. When User U3 logs in to the platform, it will be able to perform the actions thanks to the role assignments of his user group.