5.4 KiB
pageClass
| pageClass |
|---|
| 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
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.
module_list object
Override for the module listing in the left most sidebar of the Admin App.
collection_list object
Override for the collection listing in the navigation of the collections module in the Admin App.
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,
"module_list": null,
"collection_list": null,
"admin_access": true,
"app_access": true,
"users": ["0bc7b36a-9ba9-4ce0-83f0-0a526f354e07"]
}
List Roles
List all roles that exist in Directus.
Query Parameters
Supports all global query parameters.
Returns
An array of up to limit role objects. If no items are available, data will be an empty array.
GET /roles
// Response
{
"data": [
{
"id": "653925a9-970e-487a-bfc0-ab6c96affcdc",
"name": "Admin",
"icon": "supervised_user_circle",
"description": null,
"ip_access": null,
"enforce_tfa": false,
"module_list": null,
"collection_list": null,
"admin_access": true,
"app_access": true,
"users": ["0bc7b36a-9ba9-4ce0-83f0-0a526f354e07"]
},
{...},
{...}
]
}
Retrieve a Role
List an existing role by primary key.
GET /roles/:id
// Response
{
"data": {
"id": "653925a9-970e-487a-bfc0-ab6c96affcdc",
"name": "Admin",
"icon": "supervised_user_circle",
"description": null,
"ip_access": null,
"enforce_tfa": false,
"module_list": null,
"collection_list": null,
"admin_access": true,
"app_access": true,
"users": ["0bc7b36a-9ba9-4ce0-83f0-0a526f354e07"]
}
}
Create a Role
Create one or more new role(s).
Query Parameters
Supports all global query parameters.
Request Body
A partial role object or an array of partial role objects.
Returns
Returns the role object(s) for the created role(s).
POST /roles
// Request
{
"name": "Interns",
"icon": "verified_user",
"description": null,
"admin_access": false,
"app_access": true
}
// Response
{
"data": {
"id": "2e6c5fc1-e2bb-4bfc-9f74-8a91604b3b31",
"name": "Interns",
"icon": "verified_user",
"description": null,
"ip_access": null,
"enforce_tfa": false,
"module_list": null,
"collection_list": null,
"admin_access": false,
"app_access": true,
"users": null
}
}
Update a Role
Update an existing role.
Query Parameters
Supports all global query parameters.
Request Body
A partial role object.
Returns
Returns the role object for the created role.
PATCH /roles/:id
// Request
{
"icon": "attractions"
}
// Response
{
"data": {
"id": "2e6c5fc1-e2bb-4bfc-9f74-8a91604b3b31",
"name": "Interns",
"icon": "attractions",
"description": null,
"ip_access": null,
"enforce_tfa": false,
"module_list": null,
"collection_list": null,
"admin_access": false,
"app_access": true,
"users": null
}
}
Delete a Role
Delete an existing role.
Returns
Empty body.
DELETE /roles/:id
// Empty Response
Delete Multiple Roles
Delete multiple existing roles.
Request Body
An array of role primary keys
Returns
Empty body.
DELETE /roles
// Request
["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]
// Empty Response