Guides

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

PUT /users/{userId}
{
  "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

PUT /users/{userId}
{
  "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 manager
  • roles, 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

PUT /users/{userId}
{
  "teams": ["8b42b8f3-b97c-41e9-a06b-b7118522c3d7"]
}