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. |
Only Admins and Owners can view the permissions granted to each role or assign team members to roles.
#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
- Click + Add custom role at the top right of the roles screen.
- Enter a Name for the role and optionally a Description.
- Click Create.
Add custom role
The new role is added to the list with basic read permissions assigned by default. Use View permissions from the context menu to configure the full permission set.
From the context menu of a custom role, you can:
- View permissions: View and edit the content and Management API permissions for this role.
- Assign members: Assign project members to this role.
- Delete role: Permanently delete this role.
#Configure content permissions
Content permissions determine what actions users can perform on content entries in the content editor.
Add Content permissions
- Click on the custom role in the roles table to open its permissions screen.
- Click + Add permission.
- 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.
| Permission | What it allows |
|---|
Read | View content entries. Required as a baseline for all other actions. |
Create | Create new content entries. |
Update | Edit existing content entries. |
Delete | Delete content entries. |
Publish | Publish content entries to a stage. |
Unpublish | Remove content entries from a published stage. |
Read versions | View version history for a content entry. |
Use the Reset button at the bottom left of the screen to reset permissions to their default state before saving.
Management API permissions control both API access and UI visibility.
Edit Management API permissions
- Click on the custom role in the roles table.
- The screen shows only enabled permissions by default. Click Show all available permissions to see the full list.
- Use the toggles to enable or disable individual permissions.
- Use the checkboxes to select multiple permissions. The Enable selected or Disable selected bulk action appears at the top of the table.
For a read-only role, the default permissions are sufficient. No additional Management API permissions are needed.
For a publisher role, also enable Update published entries, Create new entries, Publish non-published entries, Update existing non-published entries, and Delete existing entries.
#Delete a custom role
System roles cannot be deleted. To delete a custom role:
- Open the context menu for the role.
- Select Delete role.
- Confirm the deletion in the popup.
This action cannot be undone.
Delete a custom role
#Assign members to a role
Before assigning a user to a role, they must be invited to the project. See Manage team members for instructions.
To assign team members to a role:
- Open the context menu for the role and select Assign members.
- Select one or more team members using the checkboxes.
- Click Assign.
If all current project members are already assigned to the role, a popup will let you know. Click Invite members in that popup to add new people to the project.
Assign members to a custom role
#View role permissions
To view all content and Management API permissions for a role, open the context menu and select View permissions.
From the permissions screen 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 edit permissions, use a custom role.
#Remove a user
To remove a team member from a role or from the project entirely, go to Project Settings > Team > Members. See Manage team members for full instructions.
#Permission setup examples
The following examples show common permission configurations.
Pro tip
Use the browser find command (Ctrl+F or Cmd+F) to locate specific permission names in the Management API permissions reference.
#Read-only
Content API permissions:
- Model: All
- Read: All locales, all stages
- Read versions: Enabled
No additional Management API permissions are needed. The defaults are sufficient for a read-only role.
Read-only user
#Read and publish
Content API permissions:
- Model: All
- Read: All locales, all stages
- Publish: All stages, all destination stages, all locales
- Read versions: Enabled
Additional Management API permissions to enable:
Update published entriesCreate new entriesPublish non-published entriesUpdate existing non-published entriesDelete existing entries
Read and publish setup
#By model
Select the target model from the Model dropdown when creating a content permission. Permissions will apply only to entries of that model.
Setup by models
Selecting multiple models at once is not supported, unless you select all models. To configure the same permissions on two different models, create a separate permission for each.
If the target model references other models, you must also add at least Read and Update permissions on each referenced model for actions like create, update, delete, publish, or unpublish to work correctly.
#By locale
When selecting a permission action, use the Locales dropdown to restrict it to one or more specific locales.
Setup by locales
You must also grant access to the default locale for any role that needs to create or update content.
#By content stage
Use the From stages and To stages dropdowns to restrict publish and unpublish actions to specific stages. For example, you can limit a role to publishing from Draft to a QA stage only, preventing direct publishing to Published.
Setup by content stage
Pro tip
Check out Content Workflows to learn how to use content stages for approval workflows. For help with a specific setup, contact the Hygraph support team.
#By environment
Management API permissions apply to all environments in a project. Content permissions are environment-specific, so you can configure different permissions on each environment for the same role.
For example, to give a role read-only access on the master environment and publish access on a secondary environment:
- Switch to your master environment.
- Set up the role as read-only, as described in the read-only example above.
- Switch to the secondary environment. Learn how to switch environments.
- Open the custom role and select View permissions.
- Add the Publish and Unpublish content permissions.
- Enable the additional Management API permissions required for publishing, as described in the read and publish example above.
Setup by environment
#Using conditions
Conditions let you restrict a permission to specific content entries. Instead of granting a role access to all entries in a model, you can scope it further using a GraphQL where clause.
For example, for entries with a particular field value, tag, or ID.
To add a condition when configuring a content permission:
- Open the custom role and click + Add permission.
- Select the target model from the Model dropdown.
- Check the actions you want to grant.
- Enter a JSON
where clause in the Condition field.
- Click Create to save.
Conditions
Conditions must be maintained manually. If a field is renamed or a referenced document ID changes, the condition becomes invalid. Update affected conditions whenever the underlying schema or content changes.
For the full conditions reference including syntax, examples, and constraints, see Use conditions in the content permissions documentation.
Conditions require familiarity with GraphQL where clauses. Use the API Playground to build
and test a condition before applying it to a role.
#What's next