Role

A role is a set of abilities members have within an organisation. Roles allow permissions to be granted to members of an organisation. Adding a role to a member will grant the member the permissions of that role.

Role Object

Field	Type	Description
id	snowflake	the role's id
organisation_id	snowflake	the role's organisation id
name	string	the role's alias (up to 20 characters)
description	string	a description of the role
order	integer	the role's order within the organisation
permissions	object<snowflake, Permission Grant Type>	permissions granted to this role

Get Role

GET /roles/{role.id}

Returns the role object for the given role id. Requires membership in the organisation that owns the role.

Error Responses

Status Code	Description
400	The role was not found
403	The user is not a member of the organisation

Update Role

PATCH /roles/{role.id}

Updates a role's properties or permissions. Requires the MANAGE_ROLES permission for the organisation.

All parameters for this method are optional. Only the fields provided will be updated.

Parameters

Field	Type	Description
alias	string	the role's alias (up to 20 characters)
description	string	a description of the role
permissions	object<string, Permission Grant Type>	permissions to grant or revoke for this role

Error Responses

Status Code	Description
400	The role or organisation was not found
403	The user lacks the MANAGE_ROLES permission

Delete Role

DELETE /roles/{role.id}

Deletes a role. Requires the MANAGE_ROLES permission for the organisation.

Error Responses

Status Code	Description
400	The role or organisation was not found
403	The user lacks the MANAGE_ROLES permission

List Role Members

GET /roles/{role.id}/members

Returns an array of user objects that are assigned to the role. Requires membership in the organisation that owns the role.

Error Responses

Status Code	Description
400	The role was not found
403	The user is not a member of the organisation