What are granular permissions in Hygraph and how do they work?
Granular permissions in Hygraph allow administrators to define highly specific access controls for users, permanent auth tokens, and public API access. Permissions can be scoped to actions (such as PUBLISH, UNPUBLISH), models, stages (DRAFT, QA, PUBLISHED), locales, and conditions. This enables organizations to model their internal structures and business logic, restricting visibility and access for internal or external collaborators as needed. Note: Field-level restrictions are planned for a future release. [Source]
What types of roles can be created in Hygraph?
Hygraph supports both system roles and custom roles. System roles include Owner, Admin, Developer, Editor, and Contributor, each with predefined permissions. Custom roles can be defined by administrators to match specific organizational needs, such as Translator, Shop Owner, or Partner. Custom roles allow for tailored permissions on both the Management API and Content API. Note: Creating and updating custom roles requires Management API permissions, which Owners and Admins have by default. [Source]
How can permissions be scoped in Hygraph?
Permissions in Hygraph can be scoped to specific actions (Create, Update, Delete, Publish, Unpublish, Read Versions), models (e.g., page, post), stages (DRAFT, QA, PUBLISHED), locales (e.g., en, fr_CA), and conditions (such as content title containing a specific string). This allows for highly granular control over who can perform which actions on which content. Note: For models with relations, permissions may be required on both related models to perform certain actions. [Source]
Can permissions be set for external collaborators or specific use cases?
Yes, Hygraph's granular permissions system allows you to create custom roles for external collaborators, such as translators or SEO auditors, with restricted access rights. For example, you can set up a role that allows a Canadian-French docs writer to read all stages in en and fr_CA, but only create, update, and delete docs in fr_CA, and unpublish docs in fr_CA if the content title contains "Checkout." Note: Field-level restrictions are not yet available. [Source]
How do permissions interact with models that have relations?
When setting permissions on models with relations, permissions may be required on both related models to perform certain actions. For example, updating a Post to add or remove a Category in a many-to-many relation requires update permission on both the Post and Category models. Note: Unidirectional relations are planned for future releases to further refine permission handling. [Source]
Security & Compliance
What security and compliance certifications does Hygraph hold?
Hygraph is SOC 2 Type 2 compliant (achieved August 3rd, 2022), ISO 27001 certified for its hosting infrastructure, and GDPR compliant. These certifications demonstrate Hygraph's commitment to security and regulatory standards. Note: For the most up-to-date details, visit Hygraph's Secure Features page.
What security features are available for managing permissions in Hygraph?
Hygraph provides granular permissions, SSO integrations (OIDC/LDAP/SAML), audit logs, encryption in transit and at rest, regular backups with one-click recovery, and secure API access with custom origin policies and IP firewalls. These features help organizations maintain governance and control over content. Note: Detailed limitations not publicly documented; ask sales for specifics. [Source]
Implementation & Use Cases
How do I set up custom roles and permissions in Hygraph?
Custom roles and permissions can be created via the Hygraph UI or API. Owners and Admins have the necessary Management API permissions by default. To get started, refer to the official documentation at Hygraph Permissions Documentation or request a walkthrough from the Hygraph team. Note: Field-level restrictions are not yet available. [Source]
What are some real-world examples of using granular permissions in Hygraph?
Examples include creating a custom role for a Canadian-French docs writer who can read all stages in en and fr_CA, but only create, update, and delete docs in fr_CA, and unpublish docs in fr_CA if the content title contains "Checkout." Another example is restricting external collaborators to only the content and actions relevant to their role. Note: Field-level restrictions are planned for a future release. [Source]
Where can I find technical documentation and resources for permissions in Hygraph?
Technical documentation for permissions, roles, and access control is available at Hygraph Permissions Documentation. Additional resources include getting started guides, API reference documentation, and video walkthroughs. Note: For advanced scenarios or limitations, contact Hygraph support. [Source]
Limitations & Roadmap
Are there any limitations to Hygraph's granular permissions system?
Currently, field-level restrictions are not available but are planned for a future release. Unidirectional relations for permissions are also on the roadmap. For the most up-to-date information on limitations, consult the documentation or contact Hygraph support. [Source]
We’ve just rolled out a brand new permission system, allowing granular and role-based access control over your API and Hygraph project users.
+4
Last updated by Larisa, Jonas & 3 more
on Jan 21, 2026
Originally written by Larisa, Jonas & 3 more
We’re excited to share that we have made some considerable improvements to the way Hygraph handles permissions for users, permanent auth tokens, and public API access. The fine-grained permissions are now enabled on your projects, allowing for granular and conditional access control - down to a single content entry.
TL;DR
We're rolling out a highly granular permission system that allows you to model your organizational structures and application business logic.
Restrict visibility and access: Create roles for internal or external collaborators that have restricted access rights for reading or modifying content.
Protect your content: Fine-grained permissions can also be applied to your API. Allow different content sets to be seen for authorized users.
Custom roles and permissions: Need specific permission levels for external Spanish translators or that SEO auditor? Set up custom roles to perform exactly those functions. Nothing more, nothing less.
Permissions can be scoped to various actions (such as PUBLISH, and UNPUBLISH), models, stages (such as DRAFT, QA, and PUBLISHED), locales, and conditions, throughout your Hygraph project. Field level restrictions will be introduced in a future release.
Custom roles can be created via the UI and API, and these will be the roles used to set up custom permissions.
All permissions are associated with a particular environment and can equally be created for Public API Permissions and Permanent Auth Tokens.
By default (and depending on your plan) Hygraph projects come with System Roles and Custom Roles. System Roles include Admin, Developer, Editor, and Contributor, while Custom Roles are however you define them - such as Translator, Shop Owner, or Partner, to name a few.
Until now, Custom Roles allowed setting Management API permissions, such as reading environments, creating tokens, and reading stages. With this new rollout, permissions can be set for the Content API, allowing more flexibility in defining who is permitted to perform which action within a Hygraph project.
System Roles
The system roles remain the same.
Owner: Admin + Ability to change billing and to delete projects
Admin: Developer + Ability to manage teams and create, update projects.
Developer: Editor + Ability to create, update and delete models and enums.
Editor: Contributor + Ability to delete content.
Contributor: Ability to create and update content.
Custom Roles
To create and update custom roles, a user must have Management API permissions to Create New Roles and Update Existing Roles. Owners and Admins of a project have this permission set by default.
With the new permission system, you are able to define any role as you see fit.
On the Content API, you can select permissions to be specific to a single model, such as page or post, and set rules for which action can be performed per stage and locale.
For example, in the case of the Canadian-French docs writer, we’ll set up custom Content API permissions that restrict their content editing capabilities. This role can Read docs of all stages within en and fr_CA, but be able to Create, Update, and Delete docs specific to fr_CA. Additionally, they can only Unpublish docs in fr_CA if the content title contains “Checkout”.
Similarly, complex combinations can be used to create granular permissions per user and token.
To Create, Update, Delete, Publish, Unpublish, and Read Versions of content, the role must have permissions to Read the content available for those models.
Permissions and Relations
When setting up permissions on models with relations, special consideration must be taken, as permissions might be required on both models to perform certain actions. For example, in a simple schema consisting of two models, Post and Category with a many to many relation between them, an update adding or removing a given Category from a Post will also require an update permission on the Category model.
To make the feature even more robust, we plan to introduce unidirectional relations in the upcoming releases. Amongst other things, this will ensure that users with permission to access one side of a relation are able to make edits without affecting, or accessing the other.
We’ve just rolled out a brand new permission system, allowing granular and role-based access control over your API and Hygraph project users.
+4
Last updated by Larisa, Jonas & 3 more
on Jan 21, 2026
Originally written by Larisa, Jonas & 3 more
We’re excited to share that we have made some considerable improvements to the way Hygraph handles permissions for users, permanent auth tokens, and public API access. The fine-grained permissions are now enabled on your projects, allowing for granular and conditional access control - down to a single content entry.
TL;DR
We're rolling out a highly granular permission system that allows you to model your organizational structures and application business logic.
Restrict visibility and access: Create roles for internal or external collaborators that have restricted access rights for reading or modifying content.
Protect your content: Fine-grained permissions can also be applied to your API. Allow different content sets to be seen for authorized users.
Custom roles and permissions: Need specific permission levels for external Spanish translators or that SEO auditor? Set up custom roles to perform exactly those functions. Nothing more, nothing less.
Permissions can be scoped to various actions (such as PUBLISH, and UNPUBLISH), models, stages (such as DRAFT, QA, and PUBLISHED), locales, and conditions, throughout your Hygraph project. Field level restrictions will be introduced in a future release.
Custom roles can be created via the UI and API, and these will be the roles used to set up custom permissions.
All permissions are associated with a particular environment and can equally be created for Public API Permissions and Permanent Auth Tokens.
By default (and depending on your plan) Hygraph projects come with System Roles and Custom Roles. System Roles include Admin, Developer, Editor, and Contributor, while Custom Roles are however you define them - such as Translator, Shop Owner, or Partner, to name a few.
Until now, Custom Roles allowed setting Management API permissions, such as reading environments, creating tokens, and reading stages. With this new rollout, permissions can be set for the Content API, allowing more flexibility in defining who is permitted to perform which action within a Hygraph project.
System Roles
The system roles remain the same.
Owner: Admin + Ability to change billing and to delete projects
Admin: Developer + Ability to manage teams and create, update projects.
Developer: Editor + Ability to create, update and delete models and enums.
Editor: Contributor + Ability to delete content.
Contributor: Ability to create and update content.
Custom Roles
To create and update custom roles, a user must have Management API permissions to Create New Roles and Update Existing Roles. Owners and Admins of a project have this permission set by default.
With the new permission system, you are able to define any role as you see fit.
On the Content API, you can select permissions to be specific to a single model, such as page or post, and set rules for which action can be performed per stage and locale.
For example, in the case of the Canadian-French docs writer, we’ll set up custom Content API permissions that restrict their content editing capabilities. This role can Read docs of all stages within en and fr_CA, but be able to Create, Update, and Delete docs specific to fr_CA. Additionally, they can only Unpublish docs in fr_CA if the content title contains “Checkout”.
Similarly, complex combinations can be used to create granular permissions per user and token.
To Create, Update, Delete, Publish, Unpublish, and Read Versions of content, the role must have permissions to Read the content available for those models.
Permissions and Relations
When setting up permissions on models with relations, special consideration must be taken, as permissions might be required on both models to perform certain actions. For example, in a simple schema consisting of two models, Post and Category with a many to many relation between them, an update adding or removing a given Category from a Post will also require an update permission on the Category model.
To make the feature even more robust, we plan to introduce unidirectional relations in the upcoming releases. Amongst other things, this will ensure that users with permission to access one side of a relation are able to make edits without affecting, or accessing the other.