Skip to content
On this page

Roles

Roles define a specific set of access permissions, and are the primary organizational structure for Users within the platform. Learn more about Roles.

The Role Object

id uuid
Primary key of the role.

name string
Name of the role.

icon string
Icon for the role. Displayed in the Admin App.

description string
Description for the role. Displayed in the Admin App.

ip_access csv
A CSV of IP addresses that have access to this role. Allows you to configure an allowlist of IP addresses.

enforce_tfa boolean
Whether or not Two-Factor Authentication is required for users in this role.

admin_access boolean
If this role is considered an admin role. This means that users in this role have full permissions to everything.

app_access boolean
Whether or not users in this role have access to use the Admin App.

users one-to-many
The users in this role. One-to-many to users.

json
{
	"id": "653925a9-970e-487a-bfc0-ab6c96affcdc",
	"name": "Admin",
	"icon": "supervised_user_circle",
	"description": null,
	"ip_access": null,
	"enforce_tfa": false,
	"admin_access": true,
	"app_access": true,
	"users": ["0bc7b36a-9ba9-4ce0-83f0-0a526f354e07"]
}
{
	"id": "653925a9-970e-487a-bfc0-ab6c96affcdc",
	"name": "Admin",
	"icon": "supervised_user_circle",
	"description": null,
	"ip_access": null,
	"enforce_tfa": false,
	"admin_access": true,
	"app_access": true,
	"users": ["0bc7b36a-9ba9-4ce0-83f0-0a526f354e07"]
}

List Roles

List all roles that exist in Directus.

Request

Query Parameters

Supports all global query parameters.

Response

An array of up to limit role objects. If no items are available, data will be an empty array.

Example

Retrieve a Role

List an existing role by primary key.

Query Parameters

Supports all global query parameters.

Response

Returns the requested role object.

Example

Create a Role

Create a new role.

Request

Query Parameters

Supports all global query parameters.

Request Body

A partial role object.

Response

Returns the role object for the created role.

Example

Create Multiple Roles

Create multiple new roles.

Request

Query Parameters

Supports all global query parameters.

Request Body

An array of partial role objects.

Response

Returns the role objects for the created roles.

Example

Update a Role

Update an existing role.

Request

Query Parameters

Supports all global query parameters.

Request Body

A partial role object.

Response

Returns the role object for the updated role.

Example

Update Multiple Roles

Update multiple existing roles.

Request

Query Parameters

Supports all global query parameters.

Request Body

keys Required
Array of primary keys of the roles you'd like to update.

data Required
Any of the role object's properties.

Response

Returns the role objects for the updated roles.

Example

Delete a Role

Delete an existing role.

Request

Response

Empty body.

Example

Delete Multiple Roles

Delete multiple existing roles.

Request

Request Body

An array of role primary keys

Response

Empty body.

Example