Frequently Asked Questions

Roles & Permissions Overview

What are roles and permissions in Hygraph, and why are they important?

Roles and permissions in Hygraph are essential for ensuring data safety, creating efficient workflows, and building independent teams. Each role defines what actions a user can perform and what parts of the CMS they can access. This structure helps declutter the interface for users by only showing relevant features and ensures that sensitive operations are restricted to authorized team members. Learn more.

How are content permissions and management API permissions different in Hygraph?

Content permissions in Hygraph are environment-specific, meaning their configuration applies to each environment separately. In contrast, management API permissions are global and apply to the entire project across all environments. For example, granting a role the permission to read models via the management API allows that action in all environments for the project. Details here.

System Roles & Custom Roles

What are the default system roles in Hygraph and what permissions do they have?

Hygraph provides five standard system roles that cannot be edited or deleted: Owner, Admin, Developer, Editor, and Contributor. Each has predefined permissions:

See the full table in the documentation.

Can I create custom roles in Hygraph, and who can do this?

Yes, custom roles can be created in Hygraph to match specific functionality needs. Only Project Admins and Owners can create custom roles, and this feature is available on enterprise plans. Custom roles allow for granular control over permissions, ensuring users only see and access what they need. More info.

How do I add a custom role in Hygraph?

To add a custom role, click the + Add custom role button in the custom roles form. Enter the role name and an optional description, then click Create. By default, basic Read permissions are assigned. You can further customize permissions using the View permissions option. Step-by-step guide.

What permissions can I assign to custom roles in Hygraph?

Custom roles can be assigned granular permissions, including Read, Create, Update, Delete, Publish, Unpublish, and Read versions. Permissions can be restricted by model, locale, stage, and environment. For management API permissions, you can enable or disable specific actions globally for the project. Learn more.

Managing Team Members & Assignments

How do I assign team members to roles in Hygraph?

To assign team members to a role, select the Assign members option for the desired role, choose team members using checkboxes, and click Assign. If all members are already assigned, you can invite new members to the project. Full instructions.

How can I remove a user from a role in Hygraph?

You can remove team members from a specific role by navigating to Project settings > Team > Members. For more details, see this guide.

Editing & Viewing Permissions

How do I view or edit permissions for a role in Hygraph?

To view all content and management API permissions for a role, select View Permissions from the context menu. Permissions for system roles are read-only, but you can edit permissions for custom roles. You can also assign new members to the role from this screen. More info.

How do I edit management API permissions for a custom role?

To edit management API permissions, select the custom role and use the switches to enable or disable specific permissions. By default, only enabled permissions are shown, but you can view all available permissions by clicking Show all available permissions instead. Bulk actions are available for enabling or disabling multiple permissions. Details here.

Permission Setups & Examples

How do I set up a read-only user in Hygraph?

To set up a read-only user, select all models, enable Read for all locales and stages, and enable Read versions. Management API permissions for read-only are pre-selected by default. See example.

How do I set up permissions for users who need to read and publish content?

For a read and publish setup, select all models, enable Read and Publish for all locales and stages, and enable Read versions. Then, enable management API permissions for updating published entries, creating new entries, publishing non-published entries, updating existing non-published entries, and deleting existing entries. See example.

Can I restrict permissions by model, locale, stage, or environment in Hygraph?

Yes, Hygraph allows you to restrict permissions by model, locale, stage, and environment. For example, you can grant access to only one model, specific locales, or certain content stages (like DRAFT or QA). Permissions can also be set differently for each environment. Learn more.

How do I use conditions to grant granular access to content in Hygraph?

You can use content conditions to grant users access to specific content entries or fields. For example, you can allow a user to create, update, delete, or publish only a particular entry by specifying its id. Setting up conditions requires some GraphQL knowledge. More on conditions.

Security, Compliance & Support

What security and compliance certifications does Hygraph have?

Hygraph is SOC 2 Type 2 compliant, ISO 27001 certified, and GDPR compliant. These certifications ensure enterprise-grade security and data protection. Features include SSO integrations, audit logs, encryption at rest and in transit, and sandbox environments. See security features.

What support is available if I need help with roles and permissions in Hygraph?

Hygraph offers 24/7 support via chat, email, and phone. Enterprise customers receive dedicated onboarding and expert guidance. Comprehensive documentation, video tutorials, and a community Slack channel are also available. Contact support.

Resources & Further Reading

Where can I find more documentation on permissions and roles in Hygraph?

You can find detailed documentation on permissions, authorization, and API access at the following links:

Help teams manage content creation and approval in a clear and structured way
Hygraph
Docs

#Roles and permissions

Roles are a critical part of ensuring the safety of the data stored in a CMS, creating efficient workflows, building independent teams. Each role has specific permissions which determine what the user is allowed to perform and view in the CMS.

With some roles in Hygraph, you do not see the developer functionality, which declutters the interface and makes sure you only see what is relevant to your role.

Roles and Permissions overviewRoles and Permissions overview

#System roles

System roles are the default roles in Hygraph, and cannot be edited or deleted.

There are five standard system roles in Hygraph. As part of the content team, the Owner, Editor, and Contributor roles are relevant to you.

Each role has its own set of predefined permissions, as follows:

RoleRights
OwnerAdmin + Ability to change billing and to delete projects
AdminDeveloper + Ability to manage teams and create, update projects.
DeveloperEditor + Ability to create, update and delete models and enums.
EditorContributor + Ability to delete content.
ContributorAbility to create and update content.

Since every team is different and sometimes people wear more than one hat in the company, it is possible to create custom roles.

#Custom roles

Custom Roles will let you create roles that match the functionality that they need, without having to see features they don't need. Custom roles can only be created by Project Admins and Owners. These roles are fully adjustable to provide maximum flexibility in permissions for each user working on the project.

When creating custom roles, it is important to remember to select all of the Read permissions - read and read versions - in order for the user to have the required basic functionality. If Read permissions are not selected, the user won't be able to open a content entry.

You can find roles and permissions under settings. Click here to read more about custom roles permissions.

#Add custom role

Add custom roleAdd custom role

To add a custom role, click on the + Add custom role button, located at the top right corner of the custom roles form. The Create role screen will pop up as a result.

Add a role screenAdd a role screen

Add the name of the role in the Name field, and optionally add a description in the Description field. Once you've completed this, click on the Create button to add the new custom role to the form.

Now that you've added the custom role to your project, you can select the following options in the context menu:

#Edit custom role permissions

To edit custom role permissions, click on the role on the table. The permissions screen for that role will display as a result.

Edit custom role permissionsEdit custom role permissions

In addition to the actions for the regular View Permissions screen - described here - you can add Content Permissions, and edit Management API Permissions.

#Add Content Permissions

To add Content Permissions, click on the + Add permission button. The Add permission screen will pop up as a result:

Add Content permissionsAdd Content permissions

Use the Model dropdown to select the model that permissions will be applied to. By default, the action rules will be applied to all the models in your project. However, you can choose to restrict the permissions to only one model.

Next, use the checkboxes to select which content permissions should be assigned to the custom role. When you select a checkbox, additional options might display, such as dropdowns to select Locales and Stages. This will help you customize your roles further, as the configuration is extremely granular.

NamePermissions
ReadMinimum permission required to be able to view content entries.
CreatePermission to create new content entries and save it.
UpdatePermission to make some changes to already existing content entries and save the changes.
DeletePermission to delete a content entry.
PublishPermission to publish content.
UnpublishPermission to unpublish content.
Read versionsPermission to view versions of content.

You have the option to use the Reset button located at the bottom left corner of the screen to reset the permissions to their default state.

Once you have set the permissions for the role, click on Create to save.

#Edit Management API Permissions

To edit Management API Permissions, use the switches. By default, the screen shows only the permissions that are enabled, to see the full list click on Show all available permissions instead at the top of the form.

Edit Management API permissionsEdit Management API permissions

  • Basic Read permissions are selected by default, as they are necessary for the user to have the required basic functionality. You can edit this - if needed - and select other permissions as well.
  • If you use the checkboxes to select more than one of the enabled permissions, the Disable selected bulk action appears at the top of the table.
  • If you use the checkboxes to select more than one of the disabled permissions, the Enable selected bulk action appears at the top of the table.
  • The Show all permissions link at the top of the table displays all permissions, enabled and disabled. After clicking on it, the link at the top of the table will say Show enabled permissions, and clicking on it returns you to the view where only enabled permissions are visible.

#Delete a custom role

While system roles cannot be deleted, custom roles can. To delete a custom role, select the Delete role option from the context menu.

Delete a custom roleDelete a custom role

As this action cannot be reverted, a confirmation screen will pop up.

Delete a custom role - confirmationDelete a custom role - confirmation

Click on the Delete button to confirm.

#Assign members

Follow these instructions to assign a team member to a role:

Assign members to a custom roleAssign members to a custom role

  1. Click on the Assign members option for the role you want to add members to.
  2. Select one or more team members using the checkboxes.
  3. Click Assign.

If the person you want to assign to the role has not yet been invited to the project, you can navigate to Members and invite them.

#View permissions

To view all the Content & Management API permissions associated to a role, select the View Permissions option from the context menu. A screen will display listing all the granted permissions for that role.

You can sort the permissions alphabetically by model or action, and you can filter them by actions, models, locales, and stages.

You also have the option to assign new members to the current role from this screen, by clicking on the Assign members button located at the top right corner of the screen. Clicking on this button triggers the Assign member flow that we described in the previous section.

#Removing a user

You can remove team members from a specific role in Project settings > Team > Members.

Check out this document to learn more.

#Examples

This document section provides some examples for different setups.

#Read-only user

This example shows the setup of a read-only permission on all models, on all locales and stages.

Read-only userRead-only user

Content API permissions:

  • Model dropdown: Select all.
  • Read: Select this rule for all locales and all stages.
  • Read versions: Select this rule.

For this type of read-only permission set up, the Management API Permissions will have already been pre-selected - by default - and you do not have any further setup to do.

#Read and publish setup

For a Read and Publish permissions setup, you must first set up the Content API permissions.

Read and publish setupRead and publish setup

Content API permissions:

  • Model dropdown: Select all.
  • Read: Select this rule for all locales and all stages.
  • Publish: Select this rule from all stages, to all destination stages, with all locales.
  • Read versions: Select this rule.

Once the Content API permissions are set, use the checkboxes below to select the following Management API Permissions:

  • Update published entries
  • Create new entries
  • Publish non published entries
  • Update existing non published entries
  • Delete existing entries

#Setup by models

You can choose to restrict the permissions to access only one model.

To do that you should click on the Model dropdown menu, and select the model desired for this custom role.

Setup by modelsSetup by models

#Setup by locales

If your project has several locales, then you can set up the permissions on all locales, only one, or several ones.

Setup by localesSetup by locales

When selecting a rule, simply select the locale or locales you wish to grant access to from the dropdown menu.

#Setup by content stage

Your project is created with two content stages by default (DRAFT and PUBLISHED). If your project had a QA stage, for instance, you could choose to restrict the permissions to DRAFT stage, or only allow a role to publish from the DRAFT stage to an intermediate QA stage before publishing.

Setup by content stageSetup by content stage

Simply use the dropdown menus to select From stages and To stages.

#Setup by environment

Every Hygraph project has its main environment, or master environment. By default, when creating a content based permission, the role will be created on all your environments at the same time, in an identical way.

However, you can set up different permissions per environment. For instance, you can set up a role that allows users to publish on a secondary environment and has read-only permissions on the master environment.

To set up the use case described above, follow these steps:

  1. Go to your master environment
  2. Set up a role on the master environment as a read-only role, as described here.
  3. Go to your second environment.
  4. Go to the custom role you have just created, and select View Permissions from the context menu, so you can edit them.
  5. Edit the Content API Permissions: To the Read permissions, you will add the Publishing and Unpublishing permissions.
  6. Edit the Management API Permissions: At the moment only Read permissions are selected, so you will have to add the Publishing permissions, as described here.

#Conditions

You can use conditions to grant some users less access than others. For the following example, imagine you want to set up the role permission for one model only and, additionally, you want users in this role to have access to only one content entry of this model and fields related to it.

You can do this by using content conditions. You can use fields like id for certain content entries to grant users in this role the ability to create/update/delete/publish a specified entry. The setup would be then similar to this example:

ConditionsConditions

The condition shown above would grant the user permission to read the content entry with this particular id.

#Resources

You might find the following documents useful:

  • Permissions: This document contains information on permissions, how they work, and their limits.
  • Authorization: This document contains information on public API permissions, permanent auth tokens, and API endpoints.
  • API access: This document covers the API access section of the Hygraph app as well as its subsections: Endpoints, Content API, and Permanent auth tokens.