Introducing Granular Permissions

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.

TL;DRAnchor

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

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.

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