directus/docs/configuration/users-roles-permissions.md

# Users, Roles & Permissions

> [Users](/getting-started/glossary/#users) are the individual accounts for authenticating into the API and App. Each
> user belongs to a [Role](/getting-started/glossary/#roles) which defines its access
> [Permissions](/getting-started/glossary/#permissions).

[[toc]]

## Creating a User

1. Navigate to the **User Library**
2. Click <span mi btn>add</span> in the header
3. Enter an **Email Address**
4. Optional: Complete the **other user form fields**
5. Click <span mi btn>check</span> to save the user.

## Inviting a User

1. Navigate to the **User Library**
2. Click <span mi btn sec>person_add</span> in the header
3. Enter **one or more email addresses**, separated by new lines, in the modal
4. Select the **Role** you want to assign to the user(s)
5. Click **Invite**

At this point the invited user(s) will receive an email with a link to the App where they set a password and enable
their account.

## Configuring a User

1. Navigate to the **User Library**
2. **Click on the user** you wish to manage
3. **Complete the form** of [User Fields](/app/user-directory/#editing-a-user)

The User Detail is only editable by the current user and admins, and the following fields are only available to admins:

- **Status** — Determines if an account is able to access the platform or not. Only the `active` state is able to
  authenticate, all others are simply descriptive inactive states.
  - **Draft** — An incomplete user; no App/API access
  - **Invited** — Has a pending invite to the project; no App/API access until accepted
  - **Active** — The only status that has proper access to the App and API
  - **Suspended** — A user that has been temporarily disabled; no App/API access
  - **Archived** — A soft-deleted user; no App/API access
- **Role** — The user's role determines their permissions and access
- **Token** — A user's token is an alternate way to [authenticate into the API](/reference/authentication/) using a
  static string. When NULL, the token is disabled. When enabled, ensure that a secure string is used.

## Archiving a User

1. Navigate to the **User Library**
2. Click the user you with to archive to go to their User Detail page
3. Click on <span mi btn warn>archive</span> in the header
4. Confirm this decision by clicking **Archive** in the dialog

::: warning Disables Access

Archiving uses _soft-delete_, therefore archived users are unable to access the App or API.

:::

## Deleting a User

1. Navigate to the **User Library**
2. Select one or more users you wish to delete
3. Click on <span mi btn dngr>delete</span> in the header
4. Confirm this decision by clicking **Delete** in the dialog

::: danger Irreversible Change

Unlike the soft-delete of archiving, this process is a hard-delete. Therefore, this action is permanent and can not be
undone. Please proceed with caution.

:::

## Creating a Role

1. Navigate to **Settings <span mi icon dark>chevron_right</span> Roles & Permissions**
2. Click <span mi btn>add</span> in the header
3. Enter a unique **Role Name**
4. Enabling **App Access** allows logging in to the App
5. Enabling **Admin Access** gives full permission to project data and Settings
6. Click on **Save** to save the role

## Configuring a Role

- **Permissions** — Defines the role's access permissions
- **Role Name** — This is the name of the role
- **Role Icon** — The icon used throughout the App when referencing this role
- **Description** — A helpful note that explains the role's purpose
- **App Access** — Allows logging in to the App
- **Admin Access** — Gives full permission to project data and Settings
- **IP Access** — An allow-list of IP addresses from which the platform can be accessed, empty allows all
- **Require 2FA** — Forces all users within this role to use two-factor authentication
- **Users in Role** — A list of all users within this role

## Deleting a Role

1. Navigate to **Settings <span mi icon dark>chevron_right</span> Roles & Permissions
   <span mi icon dark>chevron_right</span> [Role Name]**
2. Click <span mi btn dngr>delete</span> in the header
3. Confirm this decision by clicking **Delete** in the dialog

::: warning Users in a Deleted Role

If you delete a role that still has users in it, those users will be given a `NULL` role, which denies their App access
and limits them to the [Public Role](/configuration/users-roles-permissions/#configuring-public-permissions)
permissions. They can then be reassigned to a new role by an admin.

:::

::: warning Last Admin

You must maintain at least one role/user with Admin Access so that you can still properly manage the project.

:::

::: warning Public Role

You can not delete the Public role, as it is part of the core platform. To disable it completely, simply turn off all
Public access permissions.

:::

## Configuring Permissions

Directus possesses an extremely granular, yet easy to configure, permissions system. When creating a new role,
permissions are disabled for all project collections by default — allowing you to give explicit access to only what is
required. Individual permissions are applied to the role, and each is scoped to a specific collection and CRUD action
(create, read, update, delete).

::: warning Saves Automatically

Every change made to the permissions of a role is saved automatically and instantly.

:::

::: warning Admin Roles

If a role is set to **Admin Access** then it is granted complete access to the platform, and therefore the permission
configuration field is disabled.

:::

1. Navigate to **Settings <span mi icon dark>chevron_right</span> Roles & Permissions
   <span mi icon dark>chevron_right</span> [Role Name]**
2. Scroll to the **Permissions** section
3. **Click the icon** for the collection (row) and action (column) you want to set
4. Choose the desired permission level: <span mi icon>check</span> **All Access**, <span mi icon>block</span> **No
   Access**, or <span mi icon>rule</span> **Use Custom**

**If you selected "<span mi icon>check</span> All Access" or "<span mi icon>block</span> No Access" then setup is
complete.** If you chose to customize permissions then continue with the appropriate guide below based on the relevant
_action_.

### Create (Custom Access)

5. **Field Permissions** control which fields accept a value on create. Fields are individually toggled.
6. **Field Validation** define the rules for field values on create
7. **Field Presets** control the field defaults when creating an item

### Read (Custom Access)

5. **Item Permissions** control which items can be read, as defined by the [Filter Rules](/configuration/filter-rules)
   entered.
6. **Field Permissions** control which fields can be read. Fields are individually toggled.

::: warning Read Field Permissions

The Directus App always requires read access to the Primary Key field (eg: `id`) so it can uniquely identify items.
Also, if a Collection has "Archive" or "Sort" fields configured, those fields will also need read access to use the
App's soft-delete and manual sorting features.

:::

### Update (Custom Access)

5. **Item Permissions** control which items can be updated, as defined by [Filter Rules](/configuration/filter-rules/).
6. **Field Permissions** control which fields can be updated. Fields are individually toggled.
7. **Field Validation** define the rules for field values on update, as defined by
   [Filter Rules](/configuration/filter-rules/).
8. **Field Presets** control the field defaults when updating an item

### Delete (Custom Access)

5. **Item Permissions** control which items can be deleted, as defined by the
   [Filter Rules](/configuration/filter-rules/) entered.

---

### Configuring Public Permissions

The Public permissions control what project data is accessible without authentication. This is managed via the Public
"role", which is included in the system by default and can not be deleted.

::: warning Private by Default

All of the data within the platform is private by default. Permissions for the public role can be granted on a
case-by-case basis by administrators.

:::

### Configuring System Permissions

In addition to permissions for _your_ custom collections, you can also customize the permissions for _system_
collections. It is important to note that when App Access is enabled for a role, Directus will automatically add
permission for the necessary system collections. To edit system permissions, simply click "System Collections" at the
bottom of the permissions configuration.

There are two pre-configured options you can use for resetting the role's system permissions and ensure proper App
access. To access these, click "System Collections" to expand, and then click one of the buttons at the bottom of the
listing.

- **App Access Minimum** — The minimum permissions required to properly access the App
- **Recommended Defaults** — More permissive but balanced for a better App user experience

## Configuring Workflows

Workflows are a way to add structured stages to the flow of content authoring. They are primarily defined through the
permissions for a Collection, but can be further enhanced via email notifications, custom interfaces, and automation.
Directus supports endlessly configurable workflows, so we will only cover one simple example below.

1. To create a structured workflow for **Articles**, the first step is
   [Creating a Field](/configuration/data-model/#creating-a-field) to track the article "status" — we'll call it
   **Status**, but it can be named anything.
2. Next, create different Roles for each stage of the workflow, such as `author` and `manager`.
3. Finally, configure the Role permissions based on the possible values of that Status field, such as `draft`, `review`,
   `approved`, and `published`, so that they are properly restricted to create content and update the status.
   - The Author can create content, but only save a status of `draft` or `review`.
   - The Manager has additional permissions that allow them to save statuses of `approved` or `published`.