Roles
List Roles
List all roles that exist in Directus.
Query Parameters
Control what fields are being returned in the object.
A limit on the number of objects that are returned.
How many items to skip when fetching data.
What metadata to return in the response.
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.
Select items in collection by given conditions.
Filter by items that contain the given search query in one of their fields.
Cursor for use in pagination. Often used in combination with limit.
Responses
Unique identifier for the role.
Name of the role.
The role's icon.
Description of the role.
Optional parent role that this role inherits permissions from. Many-to-one to roles.
Nested child roles that inherit this roles permissions. One-to-many to roles. One-to-many to roles.
The policies in this role. Many-to-many to roles.
The users in this role. One-to-many to users.
Returns the total item count of the collection you're querying.
Returns the item count of the collection you're querying, taking the current filter/search parameters into account.
GET /roles
import { createDirectus, rest, readRoles } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readRoles(query_object));
POST /graphql/system
type Query {
roles: [directus_roles]
}
{
"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
Control what fields are being returned in the object.
A limit on the number of objects that are returned.
What metadata to return in the response.
How many items to skip when fetching data.
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.
Select items in collection by given conditions.
Filter by items that contain the given search query in one of their fields.
Request Body
Unique identifier for the role.
Name of the role.
The role's icon.
Description of the role.
Optional parent role that this role inherits permissions from. Many-to-one to roles.
Nested child roles that inherit this roles permissions. One-to-many to roles. One-to-many to roles.
The policies in this role. Many-to-many to roles.
The users in this role. One-to-many to users.
Responses
Unique identifier for the role.
Name of the role.
The role's icon.
Description of the role.
Optional parent role that this role inherits permissions from. Many-to-one to roles.
Nested child roles that inherit this roles permissions. One-to-many to roles. One-to-many to roles.
The policies in this role. Many-to-many to roles.
The users in this role. One-to-many to users.
Returns the total item count of the collection you're querying.
Returns the item count of the collection you're querying, taking the current filter/search parameters into account.
POST /roles
import { createDirectus, rest, createRoles } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createRoles(roles_object_array));
POST /graphql/system
type Mutation {
create_roles_items(data: [create_directus_roles_input!]!): [directus_roles]
}
{
"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.
Responses
DELETE /roles
import { createDirectus, rest, deleteRoles } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteRoles(role_id_array));
POST /graphql/system
type Mutation {
delete_roles_items(ids: [ID!]!): delete_many
}
Update Multiple Roles
Update multiple roles at the same time.
Query Parameters
Control what fields are being returned in the object.
A limit on the number of objects that are returned.
What metadata to return in the response.
How many items to skip when fetching data.
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.
Select items in collection by given conditions.
Filter by items that contain the given search query in one of their fields.
Request Body
Description of the role.
Whether or not this role enforces the use of 2FA.
ID used with external services in SCIM.
Array of IP addresses that are allowed to connect to the API as a user of this role.
Custom override for the admin app module bar navigation.
Name of the role.
Responses
Unique identifier for the role.
Name of the role.
The role's icon.
Description of the role.
Optional parent role that this role inherits permissions from. Many-to-one to roles.
Nested child roles that inherit this roles permissions. One-to-many to roles. One-to-many to roles.
The policies in this role. Many-to-many to roles.
The users in this role. One-to-many to users.
Returns the total item count of the collection you're querying.
Returns the item count of the collection you're querying, taking the current filter/search parameters into account.
PATCH /roles
import { createDirectus, rest, updateRoles } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateRoles(role_id_array, partial_role_object));
POST /graphql/system
type Mutation {
update_roles_items(ids: [ID!]!, data: update_directus_roles_input): [directus_roles]
}
{
"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
Control what fields are being returned in the object.
What metadata to return in the response.
Request Body
Description of the role.
Whether or not this role enforces the use of 2FA.
ID used with external services in SCIM.
Array of IP addresses that are allowed to connect to the API as a user of this role.
Custom override for the admin app module bar navigation.
Name of the role.
Responses
Unique identifier for the role.
Name of the role.
The role's icon.
Description of the role.
Optional parent role that this role inherits permissions from. Many-to-one to roles.
Nested child roles that inherit this roles permissions. One-to-many to roles. One-to-many to roles.
The policies in this role. Many-to-many to roles.
The users in this role. One-to-many to users.
POST /roles
import { createDirectus, rest, createRole } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(createRole(role_object));
POST /graphql/system
type Mutation {
create_roles_item(data: create_directus_roles_input!): directus_roles
}
{
"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
Unique identifier for the object.
Control what fields are being returned in the object.
What metadata to return in the response.
Responses
Unique identifier for the role.
Name of the role.
The role's icon.
Description of the role.
Optional parent role that this role inherits permissions from. Many-to-one to roles.
Nested child roles that inherit this roles permissions. One-to-many to roles. One-to-many to roles.
The policies in this role. Many-to-many to roles.
The users in this role. One-to-many to users.
GET /roles/{id}
import { createDirectus, rest, readRole } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(readRole(role_id, query_object));
type Query {
roles_by_id(id: ID!): directus_roles
}
{
"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
Unique identifier for the object.
Responses
DELETE /roles/{id}
import { createDirectus, rest, deleteRole } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(deleteRole(role_id));
POST /graphql/system
type Mutation {
delete_roles_item(id: ID!): delete_one
}
Update a Role
Update an existing role.
Query Parameters
Unique identifier for the object.
Control what fields are being returned in the object.
What metadata to return in the response.
Request Body
Description of the role.
Whether or not this role enforces the use of 2FA.
ID used with external services in SCIM.
Array of IP addresses that are allowed to connect to the API as a user of this role.
Custom override for the admin app module bar navigation.
Name of the role.
Responses
Unique identifier for the role.
Name of the role.
The role's icon.
Description of the role.
Optional parent role that this role inherits permissions from. Many-to-one to roles.
Nested child roles that inherit this roles permissions. One-to-many to roles. One-to-many to roles.
The policies in this role. Many-to-many to roles.
The users in this role. One-to-many to users.
PATCH /roles/{id}
import { createDirectus, rest, updateRole } from '@directus/sdk';
const client = createDirectus('directus_project_url').with(rest());
const result = await client.request(updateRole(role_id, partial_role_object));
POST /graphql/system
type Mutation {
update_roles_item(id: ID!, data: update_directus_roles_input): directus_roles
}
{
"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": []
}
}