mirror of
https://github.com/directus/directus.git
synced 2026-02-17 08:01:35 -05:00
817ccf3620
* Add Quickstart Guide * Update installation * Remove unused files * Update support/backing * Tweaks in concepts * Setup file structure for API reference 2.0 * Setup page layout for reference * Add clean-urls plugin * getting started updates * Finish authentication rest * getting started updates * Render stylus in 2 spaces * Various * Various * Finish activity docs * Add collections reference * Add extension reference * concepts updates * Fields/tweaks * Add files doc * Add revisions * concepts docs * More api reference * Finish rest api reference (finally) * initial concepts * More things * Add assets api ref * Move sections from file to assets * Add environment variables * contributing docs * Add field transforms page * Left align table headers * concept links * Add API config * Fix mobile nav * Add migrating a project * doc link fixes Co-authored-by: Ben Haynes <ben@rngr.org>
357 lines
5.3 KiB
Markdown
357 lines
5.3 KiB
Markdown
---
|
|
pageClass: page-reference
|
|
---
|
|
|
|
# Roles
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
Groups of users that share permissions.
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
[[toc]]
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## The Role Object
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
<div class="definitions">
|
|
|
|
`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](/reference/api/rest/users/).
|
|
|
|
</div>
|
|
</div>
|
|
<div class="right">
|
|
|
|
```json
|
|
{
|
|
"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"]
|
|
}
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## List Roles
|
|
|
|
List all roles that exist in Directus.
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
### Query Parameters
|
|
|
|
Supports all [global query parameters](/reference/api/query).
|
|
|
|
### Returns
|
|
|
|
An array of up to [limit](/reference/api/query/#limit) [role objects](#the-role-object). If no items are available, data
|
|
will be an empty array.
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `GET /roles`
|
|
|
|
```json
|
|
// 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"]
|
|
},
|
|
{...},
|
|
{...}
|
|
]
|
|
}
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## Retrieve a Role
|
|
|
|
List an existing role by primary key.
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
### Query Parameters
|
|
|
|
Supports all [global query parameters](/reference/api/query).
|
|
|
|
### Returns
|
|
|
|
Returns the requested [role object](#the-role-object).
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `GET /roles/:id`
|
|
|
|
```json
|
|
// 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"]
|
|
}
|
|
}
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## Create a Role
|
|
|
|
Create one or more new role(s).
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
### Query Parameters
|
|
|
|
Supports all [global query parameters](/reference/api/query).
|
|
|
|
### Request Body
|
|
|
|
A partial [role object](#the-role-object) or an array of partial [role objects](#the-role-object).
|
|
|
|
### Returns
|
|
|
|
Returns the [role object(s)](#the-role-object) for the created role(s).
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `POST /roles`
|
|
|
|
```json
|
|
// Request
|
|
|
|
{
|
|
"name": "Interns",
|
|
"icon": "verified_user",
|
|
"description": null,
|
|
"admin_access": false,
|
|
"app_access": true
|
|
}
|
|
```
|
|
|
|
```json
|
|
// 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
|
|
}
|
|
}
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## Update a Role
|
|
|
|
Update an existing role.
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
### Query Parameters
|
|
|
|
Supports all [global query parameters](/reference/api/query).
|
|
|
|
### Request Body
|
|
|
|
A partial [role object](#the-role-object).
|
|
|
|
### Returns
|
|
|
|
Returns the [role object](#the-role-object) for the created role.
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `PATCH /roles/:id`
|
|
|
|
```json
|
|
// Request
|
|
|
|
{
|
|
"icon": "attractions"
|
|
}
|
|
```
|
|
|
|
```json
|
|
// 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
|
|
}
|
|
}
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## Delete a Role
|
|
|
|
Delete an existing role.
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
### Returns
|
|
|
|
Empty body.
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `DELETE /roles/:id`
|
|
|
|
```json
|
|
// Empty Response
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|
|
|
|
## Delete Multiple Roles
|
|
|
|
Delete multiple existing roles.
|
|
|
|
<div class="two-up">
|
|
<div class="left">
|
|
|
|
### Request Body
|
|
|
|
An array of role primary keys
|
|
|
|
### Returns
|
|
|
|
Empty body.
|
|
|
|
</div>
|
|
<div class="right">
|
|
|
|
### `DELETE /roles`
|
|
|
|
```json
|
|
// Request
|
|
["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]
|
|
```
|
|
|
|
```json
|
|
// Empty Response
|
|
```
|
|
|
|
</div>
|
|
</div>
|
|
|
|
---
|