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.

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.

Only Admins and Owners can view the permissions granted to each role or assign team members to roles.

#Custom roles

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. Click + Add custom role at the top right of the roles screen.
2. Enter a Name for the role and optionally a Description.
3. 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

1. Click on the custom role in the roles table to open its permissions screen.
2. Click + Add permission.
3. Use the Model dropdown to select the model to apply permissions to. Select All to apply them across all models.
4. Use the checkboxes to select the actions to grant. Some actions reveal additional options for Locales and Stages.
5. Click Create to save.

Use the Reset button at the bottom left of the screen to reset permissions to their default state before saving.

#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. The screen shows only enabled permissions by default. Click Show all available permissions to see the full list.
   • For a complete reference of all available Management API permissions, see the Management API permissions reference.
3. Use the toggles to enable or disable individual permissions.
4. 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:

1. Open the context menu for the role.
2. Select Delete role.
3. 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:

1. Open the context menu for the role and select Assign members.
2. Select one or more team members using the checkboxes.
3. 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.

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

#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 entries
• Create new entries
• Publish non-published entries
• Update existing non-published entries
• Delete 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

#By locale

When selecting a permission action, use the Locales dropdown to restrict it to one or more specific locales.

Setup by locales

#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

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

1. Switch to your master environment.
2. Set up the role as read-only, as described in the read-only example above.
3. Switch to the secondary environment. Learn how to switch environments.
4. Open the custom role and select View permissions.
5. Add the Publish and Unpublish content permissions.
6. 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:

1. Open the custom role and click + Add permission.
2. Select the target model from the Model dropdown.
3. Check the actions you want to grant.
4. Enter a JSON where clause in the Condition field.
5. 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.

#What's next

• Manage team members: Invite members and manage project access.
• Content permissions: Detailed reference for content permission rules, limits, and conditions.
• Management API permissions: Full reference for all Management API permission options.
• Authorization: Public API permissions, PATs, and endpoints.