Introducing Granular Permissions

We’ve just rolled out a brand new permission system, allowing granular and role-based access control over your API and GraphCMS project users.

Jonas Faber
Pablo Fernandez Busch
Larisa, Jonas, & 3 more
Granular Permissions in GraphCMS

We’re excited to share that we have made some considerable improvements to the way GraphCMS 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.


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

To start setting up custom roles and permissions, refer to our docs on the feature.

Here’s a quick video from Jamie walking through your project API Access settings.

Roles and PermissionsAnchor

By default (and depending on your plan) GraphCMS 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 GraphCMS project.

System RolesAnchor

System Roles in GraphCMS

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 RolesAnchor

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.

Custom Roles in GraphCMS

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.

Canadian French Docs Writer

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 RelationsAnchor

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.

To get started with Custom Roles and Content-based permissions, reach out to us for a walkthrough, or catch up on the docs.

  • Larisa Kristya
  • Jonas Faber
  • Pablo Fernandez Busch
  • Somasundaram Ayyappan
  • Carlos Rufo
  • Larisa Kristya

    Frontend Engineer

    Larisa is an engineer on the frontend team at GraphCMS.

  • Software Engineer

    Jonas is part of the backend engineering team at GraphCMS, and as one of the earliest members on the crew, makes sure that things are running smoothly. Outside of work he's a big fan of building custom keyboards.

  • Pablo Fernandez Busch

    Backend Lead

    Pablo is an engineering lead at GraphCMS.

  • Somasundaram Ayyappan

    Software Engineer

    Somu is a Fullstack Engineer on the frontend team at GraphCMS.

  • Carlos Rufo

    Software Engineer

    Carlos is an Engineering lead at GraphCMS, focused on product growth and improving the developer experience.

  • Previous
  • 1
  • 2
  • 3
  • 4
  • 5
  • Next

Related articles

It's Easy To Get Started

GraphCMS plans are flexibly suited to accommodate your growth. Get started for free, or request a demo to discuss larger projects with more complex needs