Roles

Roles are the primary organizational structure for users within the platform.

List Roles

List all roles that exist in Directus.

Query Parameters

fields

array

Control what fields are being returned in the object.

limit

integer

A limit on the number of objects that are returned.

offset

integer

How many items to skip when fetching data.

meta

string

What metadata to return in the response.

sort

array

How to sort the returned items. sort is a CSV of fields used to sort the fetched items. Sorting defaults to ascending (ASC) order but a minus sign (-) can be used to reverse this to descending (DESC) order. Fields are prioritized by their order in the CSV. You can also use a ? to sort randomly.

filter

Select items in collection by given conditions.

string

Filter by items that contain the given search query in one of their fields.

page

integer

Cursor for use in pagination. Often used in combination with limit.

Response

Successful request

data

array

meta

object

GET /roles

Response Example

{
  "data": [
    {
      "id": "2f24211d-d928-469a-aea3-3c8f53d4e426",
      "name": "Administrator",
      "icon": "verified_user",
      "description": "Admins have access to all managed data within the system by default",
      "children": [],
      "policies": [],
      "users": []
    }
  ],
  "meta": {}
}

Create Multiple Roles

Create multiple new roles.

Query Parameters

fields

array

Control what fields are being returned in the object.

limit

integer

A limit on the number of objects that are returned.

meta

string

What metadata to return in the response.

offset

integer

How many items to skip when fetching data.

sort

array

filter

Select items in collection by given conditions.

string

Filter by items that contain the given search query in one of their fields.

Request Body

data

array

Response

Successful request

data

array

meta

object

POST /roles

Response Example

{
  "data": [
    {
      "id": "2f24211d-d928-469a-aea3-3c8f53d4e426",
      "name": "Administrator",
      "icon": "verified_user",
      "description": "Admins have access to all managed data within the system by default",
      "children": [],
      "policies": [],
      "users": []
    }
  ],
  "meta": {}
}

Delete Multiple Roles

Delete multiple existing roles.

Query Parameters

Request Body

An array of role primary keys.

[array]

array

DELETE /roles

Update Multiple Roles

Update multiple roles at the same time.

Query Parameters

fields

array

Control what fields are being returned in the object.

limit

integer

A limit on the number of objects that are returned.

meta

string

What metadata to return in the response.

offset

integer

How many items to skip when fetching data.

sort

array

filter

Select items in collection by given conditions.

string

Filter by items that contain the given search query in one of their fields.

Request Body

keys

array

data

object

Response

Successful request

data

array

meta

object

PATCH /roles

Response Example

{
  "data": [
    {
      "id": "2f24211d-d928-469a-aea3-3c8f53d4e426",
      "name": "Administrator",
      "icon": "verified_user",
      "description": "Admins have access to all managed data within the system by default",
      "children": [],
      "policies": [],
      "users": []
    }
  ],
  "meta": {}
}

Create a Role

Create a new role.

Query Parameters

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

Request Body

description

string

Description of the role.

enforce_tfa

boolean

Whether or not this role enforces the use of 2FA.

external_id

string

ID used with external services in SCIM.

ip_access

array

Array of IP addresses that are allowed to connect to the API as a user of this role.

module_listing

string

Custom override for the admin app module bar navigation.

name

string

Name of the role.

Response

Successful request

data

object

POST /roles‎

Response Example

{
  "data": {
    "id": "2f24211d-d928-469a-aea3-3c8f53d4e426",
    "name": "Administrator",
    "icon": "verified_user",
    "description": "Admins have access to all managed data within the system by default",
    "children": [],
    "policies": [],
    "users": []
  }
}

Retrieve a Role

Retrieve a single role by unique identifier.

Query Parameters

string

Unique identifier for the object.

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

Response

Successful request

data

object

GET /roles/{id}

Response Example

{
  "data": {
    "id": "2f24211d-d928-469a-aea3-3c8f53d4e426",
    "name": "Administrator",
    "icon": "verified_user",
    "description": "Admins have access to all managed data within the system by default",
    "children": [],
    "policies": [],
    "users": []
  }
}

Delete a Role

Delete an existing role.

Query Parameters

string

Unique identifier for the object.

DELETE /roles/{id}

Update a Role

Update an existing role.

Query Parameters

string

Unique identifier for the object.

fields

array

Control what fields are being returned in the object.

meta

string

What metadata to return in the response.

Request Body

description

string

Description of the role.

enforce_tfa

boolean

Whether or not this role enforces the use of 2FA.

external_id

string

ID used with external services in SCIM.

ip_access

array

Array of IP addresses that are allowed to connect to the API as a user of this role.

module_listing

string

Custom override for the admin app module bar navigation.

name

string

Name of the role.

Response

Successful request

data

object

PATCH /roles/{id}

Response Example

{
  "data": {
    "id": "2f24211d-d928-469a-aea3-3c8f53d4e426",
    "name": "Administrator",
    "icon": "verified_user",
    "description": "Admins have access to all managed data within the system by default",
    "children": [],
    "policies": [],
    "users": []
  }
}