Roles

List of valid attributes:

Attribute	Description	Specifics
account_id	ID of the account the role belongs to	Cannot be set
default	Tells if the role is default and used to connect users to teams when no role is specified	Either true or false. There must be at least 1 account-scoped default role.
discarded_at	Null or timestamp of removal	Cannot be set
name	Name of the role	Must be set, Length 1-50 characters
rights	All rights the role grants	See below
role_type	Is the role user generated or from a system template	Either custom or system, Cannot be set
scope	Defines what scope the role is being applied on	Values allowed are account, team, chat, Can only be set on create

Rights

Attribute rights expects an object where each key stands for the group of rights, ie. user. Its value is an object itself where allowed keys are create, read, update, delete and in one case manage (team_membership). Allowed values are true or false but only true-values are saved so you don’t need to send key-value pairs, where value is false. Always send all rights you want to grant in a role because every update replaces the whole rights-object. The easiest way of getting a full list of allowed groups of rights is by retrieving all system roles of the account.

Meta data: Permissions

Group	Description
actions	Contains permissions to edit or delete the role. rights.edit determines if the rights inside a role can be changed

Create

Example request:

{
  "data": {
    "type": "role",
    "attributes": {
      "name": "Role"
    }
  }
}

Example response:

{
  "data": [
    {
      "id": "7f0d0f1a-6852-4634-89c0-9418fb8dc71b",
      "type": "role",
      "attributes": {
        ...
      }
    }
  ]
}

This endpoint creates a role.

HTTP Request

POST /api/v1/roles

Update

Example request:

{
  "data": {
    "type": "role",
    "attributes": {
      "name": "Updated Role"
    }
  }
}

Example response:

{
    "data": {
        "id": "b1d925db-e688-4fa0-9432-db8db55ed370",
        "type": "role",
        "attributes": {
        ...
        }
    }
}

This endpoint updates a role.

HTTP Request

PUT /api/v1/roles/:role_id

URL Parameters

Parameter	Description
role_id	ID of the role to be updated

Show

Example response:

{
    "data": {
        "id": "7182c2bb-ec46-4675-bd56-413ba862dd1e",
        "type": "role",
        "attributes": {
        ...
        }
    }
}

This endpoint returns a role.

HTTP Request

GET /api/v1/roles/:role_id

URL Parameters

Parameter	Description
role_id	The ID of the role to return

List

Example response:

{
  "data": [
    {
      "id": "3aab0a84-8ed3-4ddf-8572-f1799bb60e0a",
      "type": "role",
      "attributes": {
        ...
      }
    },
    {
      ...
    }
  ]
}

This endpoint returns a list of roles.

HTTP Request

GET /api/v1/roles

Delete

Example response:

{
  "data": {
    "id": "d567ce32-37c7-43de-8e65-ed48944d9c91",
    "type": "role",
    "attributes": {
      ...
    }
  }
}

This endpoint deletes a role.

HTTP Request

DELETE /api/v1/roles/:role_id

URL Parameters

Parameter	Description
role_id	The ID of the role to delete