Users, roles and teams
People in your organisation can be grouped and given permissions in three ways:
- Attributes label people, such as fire marshal, first aider or key holder.
- Roles decide what people can do, through scopes.
- Teams add structure, and give every member the team's roles.
To add people, invite them or create them directly. GET /available-scopes lists the scopes you can put in a role.
All three are assigned with PUT /users/{userId} by sending a list of IDs. The list replaces what the user had before, so send an empty array to remove them all.
Attributes
Create an attribute with POST /attributes. name must be unique in your organisation and between 3 and 50 characters.
{
"name": "Fire Marshal"
}Update it with PUT /attributes/{attributeId} and the same body. Include the attribute's id in the body too: without it, sending the attribute's current name fails the uniqueness check. Deleting an attribute removes it from everyone who had it, but doesn't delete those users.
Assigning attributes
{
"attributes": ["0a4b7cf2-8b1e-4f6e-9a2d-3f0f8a6c1e11"]
}Roles
Roles control what people can do. You might let only people with a "Finance" role see billing, for example.
Create a role with POST /roles. name and scopes are required; scopes needs at least one valid scope. description is optional, up to 255 characters.
{
"name": "User",
"description": "Access only to desk and room bookings",
"scopes": [
"read",
"write",
"users.read",
"assets.read",
"websocket.auth",
"roles.read",
"bookings.view",
"bookings.create.own",
"meetings.read",
"meetings.manage",
"office.attendance.view",
"users.status.view",
"users.status.edit"
]
}Update it with PUT /roles/{roleId} and the same body. Deleting a role doesn't delete the users who had it.
Assigning roles
{
"roles": ["f588101c-4a5a-46b5-8ec9-88f69c12a787"]
}Teams
Teams add hierarchy, and let you give roles to many people at once. Create a Finance team with the Finance role, and everyone you add to it gets that role.
Create a team with POST /teams. name is required. You can also send:
parent_id, if it's a sub-team, such as "Receivables" within "Finance"manager_id, if the team has a managerroles, the IDs of roles every member gets
{
"name": "Receivables",
"parent_id": "8b42b8f3-b97c-41e9-a06b-b7118522c3d7",
"manager_id": "64ca29d5-dc00-42ff-9aad-9baaa00ec66a",
"roles": ["f588101c-4a5a-46b5-8ec9-88f69c12a787"]
}Update it with PUT /teams/{teamId} and the same body. A team can't be made a sub-team of itself or of any of its own sub-teams. Deleting a team doesn't delete its members.
Assigning teams
{
"teams": ["8b42b8f3-b97c-41e9-a06b-b7118522c3d7"]
}