# 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.

| Role        | Rights                                                                                       |
|-------------|----------------------------------------------------------------------------------------------|
| Owner       | All Admin rights, plus the ability to change billing settings and delete the project.        |
| Admin       | All Developer rights, plus the ability to manage team members and create or update projects. |
| Developer   | All Editor rights, plus the ability to create, update, and delete models and enumerations.   |
| Editor      | All Contributor rights, plus 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.