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.
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
#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
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
- Under Custom roles, click Add custom role.
- Enter a Name for the role and optionally a Description.
- Click Create.
Add custom role
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 for more information.
- Read versions. This is required for versioning to display correctly in the content editor.
- Add a permission
- Click on the custom role in the roles table to open its permissions screen.
- 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.
- Click Create to save.
For what each action means, including locales and stages, see Content permissions. For how to scope a permission by model, locale, stage, environment, or condition, see 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
- 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
Management API permissions control both API access and UI visibility.
- Click on the custom role in the roles table.
- 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.
#Manage custom role
Manage custom role
#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 and 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.
#Assign members
Before assigning a user to a role, they must be invited to the project. To assign project members to a custom role:
- Under the Custom roles section, click Assign members next to the role name.
- Select one or more team members using the checkboxes.
- Click Save changes.
#Duplicate role
System roles cannot be duplicated. To duplicate a custom role:
- Under the Custom roles section, click ... to open the context menu for the role.
- 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:
- Under the Custom roles section, click ... to open the context menu for the role.
- Select Delete role.
- Confirm the deletion in the popup.
This action cannot be undone.
#What's next