# Roles

Learn how to manage system roles, create custom roles, configure content and Management API permissions, and set up role-based access in your Hygraph project.

Roles determine what users can see and do in your Hygraph project. Each role carries a set of **content permissions**, which govern access to content entries, and **Management API permissions**, which determine what a user can do in the UI and through the API.

**Note:**
**Content permissions are environment-specific.** Their configuration is applied per environment. If you are working with multiple environments, configure content permissions separately for each one.

**Management API permissions are global.** They apply across all environments in a project.

Hygraph provides five built-in system roles and supports custom roles for projects on enterprise plans. To access roles and permissions, navigate to **Project Settings > Team > Roles & Permissions**.

![Roles and Permissions overview](https://hygraph.com/images/docs/user-guides/roles-and-permissions/roles-and-permissions-overview.png)

## System roles

System roles are built into every Hygraph project. They cannot be edited or deleted. Every system role can read content and the schema, and can open project settings, team settings, and apps.

| Role        | Rights                                                                                       |
|-------------|----------------------------------------------------------------------------------------------|
| Owner       | All Admin rights, and the ability to change billing settings, clone, share, and delete the project.        |
| Admin       | All Developer rights, and the ability to manage team members and create or update projects. |
| Developer   | All Editor rights, and the ability to create, update, and delete models and enumerations.   |
| Editor      | All Contributor rights, and the ability to delete content.                                  |
| Contributor | Ability to create and update content.                                                        |

For system roles, **Admins** and **Owners** can:
- Click a system role to view its permissions. Permissions for system roles are read-only.
- Click **Assign members** on the role row to assign team members to that role.

## Custom roles

**Warning:**
Custom roles are available on Enterprise plans only.

Custom roles let you define exactly what a user can see and do, without exposing features that are not relevant to their work. Only project **Admins** and **Owners** can create and manage custom roles.

When configuring a custom role, always include the **Read** and **Read versions** content permissions. Without **Read**, users cannot open content entries. Without **Read versions**, versioning will not display correctly in the content editor.

### Create a custom role

1. Under **Custom roles**, click **Add custom role**.
2. Enter a **Name** for the role and optionally a **Description**.
3. Click **Create**.

![Add custom role](https://hygraph.com/images/docs/user-guides/roles-and-permissions/add-custom-role.png)

The new role is created with default **Management API** permissions. It does not get content permissions yet. Click the role to add content permissions and adjust Management API permissions.

### Configure content permissions

Content permissions determine what actions users can perform on content entries in the content editor.

**Pro Tip:**
    Custom roles have no content permissions by default. At a minimum, a custom role that uses the content editor need the following permissions:
        - **Read** access on the `User` system model. This is important for custom roles that interact with the UI, as user attribution fields (`createdBy`, `updatedBy`, and `publishedBy`) will not display without these permissions. Missing these permissions can also cause `not allowed` errors when mutating content from the content editor. See [System fields: User fields](https://hygraph.com/docs/api-reference/schema/system-fields#user-fields) for more information.
        - **Read versions**. This is required for versioning to display correctly in the content editor.

**Add a permission**

1. Click on the custom role in the roles table to open its permissions screen.
2. Under **Content permissions**, click **Add permissions**. If there are no content permissions yet, the empty state offers **Add permissions** and **Initialize defaults**. **Initialize defaults** grants **Read** on all models for all locales, scoped to the default public content delivery stage.
- Use the **Model** dropdown to select the model to apply permissions to. Select **All** to apply them across all models.
- Use the checkboxes to select the actions to grant. Some actions reveal additional options for **Locales** and **Stages**. 
5. Click **Create** to save.

For what each action means, including locales and stages, see [Content permissions](https://hygraph.com/docs/getting-started/access-and-permissions/content-api-permissions#permission-actions). For how to scope a permission by model, locale, stage, environment, or condition, see [Scope content permissions](https://hygraph.com/docs/getting-started/access-and-permissions/content-api-permissions#scope-content-permissions).

**Edit a permission**

**Edit** is available only when the permission has locale or stage settings. Click the context menu for a custom role, and click **Edit**. You can update the locale or stage for the content permission.

![Edit permissions](https://hygraph.com/images/docs/user-guides/api-access/edit-permissions.png)

**Delete a permission**

Click the context menu for a custom role, and click **Delete**. Confirm the deletion in the dialog that appears. This action is permanent and cannot be undone.

![Delete permissions](https://hygraph.com/images/docs/user-guides/api-access/delete-permissions.png)

### Configure Management API permissions

Management API permissions control both API access and UI visibility.

1. Click on the custom role in the roles table.
2. Under **Management API**, the table lists all available permissions. Enabled permissions are toggled on. You can perform the following actions:
    - Use **Group by Domain** or **Group by Action** to group the list.
    - Filter the list with **All permissions**, **Enabled permissions**, or **Disabled permissions**.
    - Use the toggles to enable or disable individual permissions.
    - Use the checkboxes to select multiple permissions, and then enable or disable them in bulk.

Some Management API permissions are **UI-only** and have no effect on a PAT. For what each permission does for roles versus tokens, see [Management API permissions](https://hygraph.com/docs/getting-started/access-and-permissions/management-api-permissions).

## Manage custom role

![Manage custom role](https://hygraph.com/images/docs/user-guides/roles-and-permissions/manage-custom-role.png)

### View permissions

Click the custom role to view the content and Management API permissions associated with it. You can:

- Sort permissions alphabetically by model or action.
- Filter permissions by action, model, locale, and stage.
- Assign new members to the role by clicking **Assign members** at the top right.

Permissions for system roles are read-only. To add or change permissions on that screen, see [Configure content permissions](#configure-content-permissions) and [Configure Management API permissions](#configure-management-api-permissions). 

For combined permission sets for a job, such as a read-only reviewer or a publisher, see [Permission combinations by job](https://hygraph.com/docs/getting-started/access-and-permissions/permission-combinations-by-job).

### Assign members

Before assigning a user to a role, they must be [invited to the project](https://hygraph.com/docs/getting-started/access-and-permissions/manage-team-members#invite-team-members). To assign project members to a custom role:

1. Under the **Custom roles** section, click **Assign members** next to the role name.
2. Select one or more team members using the checkboxes.
3. Click **Save changes**.

### Duplicate role

System roles cannot be duplicated. To duplicate a custom role:

1. Under the **Custom roles** section, click **...** to open the context menu for the role.
2. Click **Duplicate role**.

The copied role includes the source role's Management API permissions and content permissions in every environment. Assigned members are not copied.

Duplicating a role requires the **Create new roles** permission, and a custom role seat must be available on the plan.

### Delete role

System roles cannot be deleted. You can permanently delete a custom role. To delete a custom role:

1. Under the **Custom roles** section, click **...** to open the context menu for the role.
2. Select **Delete role**.
3. Confirm the deletion in the popup.

This action cannot be undone.

## What's next

- [Team members](https://hygraph.com/docs/getting-started/access-and-permissions/manage-team-members): Invite members and manage project access.
- [Content permissions](https://hygraph.com/docs/getting-started/access-and-permissions/content-api-permissions): Detailed reference for content permission rules, limits, and conditions.
- [Management API permissions](https://hygraph.com/docs/getting-started/access-and-permissions/management-api-permissions): Full reference for all Management API permission options.