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.
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
UNPUBLISH), models, stages (such as
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
Contributor, while Custom Roles are however you define them - such as
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.
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.
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
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
fr_CA, but be able to
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.
Read Versionsof content, the role must have permissions to
Readthe 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,
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
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.