directus/docs/reference/system/roles.md

description, readTime, pageClass

description	readTime	pageClass
REST and GraphQL API documentation on the Roles collection in Directus.	5 min read	page-reference

Roles

Roles 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 Data Studio.

description string
Description for the role. Displayed in the Data Studio.

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

policies many-to-many
The policies in this role. Many-to-many to policies.

parent many-to-one
The parent for this role. Many-to-one to roles.

children one-to-many
The roles in this role. One-to-many to roles.

{
	"id": "653925a9-970e-487a-bfc0-ab6c96affcdc",
	"name": "Admin",
	"icon": "supervised_user_circle",
	"description": null,
	"policies": ["3a4b131d-34f8-46e8-b128-5212aa9b7f72"],
	"parent": "7fdbad2a-890d-4d8a-ad1d-97ff86bc254d",
	"children": ["1d5cba05-2d9e-47a2-9594-e00b55ffdb3e"],
	"users": ["0bc7b36a-9ba9-4ce0-83f0-0a526f354e07"]
}

List Roles

List all roles that exist in Directus.

Request

GET /roles

SEARCH /roles

If using SEARCH you can provide a query object as the body of your request.

Learn more about SEARCH ->

POST /graphql/system

type Query {
	roles: [directus_roles]
}

import { createDirectus, rest, readRoles } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(readRoles(query_object));

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

GET /roles

SEARCH /roles

POST /graphql/system

query {
	roles {
		id
		name
		users {
			email
		}
	}
}

import { createDirectus, rest, readRoles } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readRoles({
		fields: ['*'],
	})
);

Retrieve a Role

List an existing role by primary key.

GET /roles/:id

POST /graphql/system

type Query {
	roles_by_id(id: ID!): directus_roles
}

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));

Query Parameters

Supports all global query parameters.

Response

Returns the requested role object.

Example

GET /roles/b4cb3b64-8580-4ad9-a099-eade6da24302

POST /graphql/system

query {
	roles_by_id(id: 2) {
		id
		name
		users {
			email
		}
	}
}

import { createDirectus, rest, readRole } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	readRole('39a178f6-d4d6-40e1-b0e7-ec6daaac8747', {
		fields: ['*'],
	})
);

Create a Role

Create a new role.

Request

POST /roles

Provide a role object as the body of your request.

POST /graphql/system

type Mutation {
	create_roles_item(data: create_directus_roles_input!): directus_roles
}

import { createDirectus, rest, createRole } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(createRole(role_object));

Query Parameters

Supports all global query parameters.

Request Body

A partial role object.

Response

Returns the role object for the created role.

Example

POST /roles

{
	"name": "Interns",
	"icon": "verified_user",
	"description": null
}

POST /graphql/system

mutation {
	create_roles_item(
		data: { name: "Interns", icon: "verified_user", description: null }
	) {
		id
		name
		users {
			email
		}
	}
}

import { createDirectus, rest, createRole } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createRole({
		name: 'Interns',
		icon: 'verified_user',
		description: null
	})
);

Create Multiple Roles

Create multiple new roles.

Request

POST /roles

Provide an array of role objects as the body of your request.

POST /graphql/system

type Mutation {
	create_roles_items(data: [create_directus_roles_input!]!): [directus_roles]
}

import { createDirectus, rest, createRoles } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(createRoles(role_object_array));

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

POST /roles

[
	{
		"name": "Interns",
		"icon": "verified_user",
		"description": null
	},
	{
		"name": "Customers",
		"icon": "person",
		"description": null
	}
]

POST /graphql/system

mutation {
	create_roles_items(
		data: [
			{ name: "Interns", icon: "verified_user", description: null }
			{ name: "Customers", icon: "person", description: null }
		]
	) {
		id
		name
		users {
			email
		}
	}
}

import { createDirectus, rest, createRoles } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	createRoles([
		{
			name: 'Interns',
			icon: 'verified_user',
			description: null
		},
		{
			name: 'Customers',
			icon: 'person',
			description: null
		},
	])
);

Update a Role

Update an existing role.

Request

PATCH /roles/:id

Provide a partial role object as the body of your request.

POST /graphql/system

type Mutation {
	update_roles_item(id: ID!, data: update_directus_roles_input): directus_roles
}

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));

Query Parameters

Supports all global query parameters.

Request Body

A partial role object.

Response

Returns the role object for the updated role.

Example

PATCH /roles/c86c2761-65d3-43c3-897f-6f74ad6a5bd7

{
	"icon": "attractions"
}

POST /graphql/system

mutation {
	update_roles_item(id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", data: { icon: "attractions" }) {
		id
		name
		users {
			email
		}
	}
}

import { createDirectus, rest, updateRole } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateRole('a262a7f6-9ed4-423d-8cd2-3ee3b2d2a658', {
		icon: "attractions",
	})
);

Update Multiple Roles

Update multiple existing roles.

Request

PATCH /roles

{
	"keys": role_id_array,
	"data": partial_role_object
}

POST /graphql/system

type Mutation {
	update_roles_items(ids: [ID!]!, data: update_directus_roles_input): [directus_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));

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

PATCH /roles

{
	"keys": ["c86c2761-65d3-43c3-897f-6f74ad6a5bd7", "6fc3d5d3-a37b-4da8-a2f4-ed62ad5abe03"],
	"data": {
		"icon": "attractions"
	}
}

POST /graphql/system

mutation {
	update_roles_items(
		ids: ["c86c2761-65d3-43c3-897f-6f74ad6a5bd7", "6fc3d5d3-a37b-4da8-a2f4-ed62ad5abe03"]
		data: { icon: "attractions" }
	) {
		id
		name
		users {
			email
		}
	}
}

import { createDirectus, rest, updateRoles } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	updateRoles(['a262a7f6-9ed4-423d-8cd2-3ee3b2d2a658', '1792dc2c-6142-4723-ae40-698d082ddc5e'], {
		icon: "attractions"
	})
);

Delete a Role

Delete an existing role.

Request

DELETE /roles/:id

POST /graphql/system

type Mutation {
	delete_roles_item(id: ID!): delete_one
}

import { createDirectus, rest, deleteRole } from '@directus/sdk';

const client = createDirectus('directus_project_url').with(rest());

const result = await client.request(deleteRole(role_id));

Response

Empty body.

Example

DELETE /roles/c86c2761-65d3-43c3-897f-6f74ad6a5bd7

POST /graphql/system

mutation {
	delete_roles_item(id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7") {
		id
	}
}

import { createDirectus, rest, deleteRole } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteRole('1792dc2c-6142-4723-ae40-698d082ddc5e'));

Delete Multiple Roles

Delete multiple existing roles.

Request

DELETE /roles

Provide an array of role IDs as the body of your request.

POST /graphql/system

type Mutation {
	delete_roles_items(ids: [ID!]!): delete_many
}

import { createDirectus, rest, deleteRoles } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(deleteRoles(role_id_array));

Request Body

An array of role primary keys

Response

Empty body.

Example

DELETE /roles

["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]

POST /graphql/system

mutation {
	delete_roles_items(ids: ["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]) {
		ids
	}
}

import { createDirectus, rest, deleteRoles } from '@directus/sdk';

const client = createDirectus('https://directus.example.com').with(rest());

const result = await client.request(
	deleteRoles(['a262a7f6-9ed4-423d-8cd2-3ee3b2d2a658', '1792dc2c-6142-4723-ae40-698d082ddc5e'])
);