60df20d780
* Simplified generics and imports for items page snippets * Simplified generics and imports for files page snippets * Fixing simplified generic snippets in items page * Simplified generics and imports for activity page snippets * Simplified generics and imports for collections page snippets * Simplified generics and imports for dashboards page snippets * Simplified generics and imports for extensions page snippets * Simplified generics and imports for fields page snippets * Simplified generics and imports for flows page snippets * Simplified generics and imports for folders page snippets * Simplified generics and imports for notifications page snippets * Simplified generics and imports for operations page snippets * Simplified generics and imports for panels page snippets * Simplified generics and imports for permissions page snippets * Simplified generics and imports for presets page snippets * Simplified generics and imports for relations page snippets * Simplified generics and imports for relations page snippets * Simplified generics and imports for revisions page snippets * Simplified generics and imports for roles page snippets * Consolidated imports for schema page snippets * Simplified generics and imports for server page snippets * Simplified generics and imports for settings page snippets * Fixed mixed up snippets and simplified generics and imports for shares page snippets * Simplified generics and imports for translation page snippets * Fixed mixed up snippets and simplified generics and imports for user page snippets * Simplified generics and imports fo uutilitie pages snippets * Simplified generics and imports for webhook pages snippets * Simplified generics and imports for authentication pages snippets * Consolidated imports for query pages sdk snippets * Format files * Update lockfile * Fix spelling * Format snippets * Aling `result` const * Small clean-ups - Align `SEARCH` snippets, move "Learn more..." next to other hint - ids -> IDs - Other alignments --------- Co-authored-by: Bevis Halsey-Perry <hi@be7.is> Co-authored-by: Pascal Jufer <pascal-jufer@bluewin.ch>
14 KiB
description, readTime, pageClass
| description | readTime | pageClass |
|---|---|---|
| REST and GraphQL API documentation on the Roles collection in Directus. | 5 min read | page-reference |
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.
{
"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
GET /roles
SEARCH /roles
If using SEARCH you can provide a query object as the body of your request.
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,
"admin_access": false,
"app_access": true
}
POST /graphql/system
mutation {
create_roles_item(
data: { name: "Interns", icon: "verified_user", description: null, admin_access: false, app_access: true }
) {
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,
admin_access: false,
app_access: true,
})
);
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,
"admin_access": false,
"app_access": true
},
{
"name": "Customers",
"icon": "person",
"description": null,
"admin_access": false,
"app_access": false
}
]
POST /graphql/system
mutation {
create_roles_items(
data: [
{ name: "Interns", icon: "verified_user", description: null, admin_access: false, app_access: true }
{ name: "Customers", icon: "person", description: null, admin_access: false, app_access: false }
]
) {
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,
admin_access: false,
app_access: true,
},
{
name: 'Customers',
icon: 'person',
description: null,
admin_access: false,
app_access: false,
},
])
);
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', {
admin_access: true,
})
);
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'], {
admin_access: true,
})
);
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'])
);