Permissions

The advanced permissions feature allows to configure granular permissions to access content from a GraphCMS project.

The system allows to setup different kinds of permissions for Public API, individual Permanent Auth Tokens (PATs) and also custom roles, if applicable as part of the GraphCMS project's plan. With this functionality, it is possible, for example, to expose only part of the content via Public API, or allow for reading and mutating content for certain models using a particular PAT.

How does it work?Anchor

Content permissions are setup on a per project's environment basis, this means that, for example, a master and development environments could be setup with different permissions as needed.

As for the permissions themselves, the user can choose to setup permissions that apply to all models or restrict access to specific models. With the latter, an optional condition to restrict access further can be used.

ActionsAnchor

The permission system is based on 7 different action types: Read, Read versions, Create, Update, Delete, Publish and Unpublish. Setting permissions for each of these actions will grant the target (Public API, PAT or custom role) permission to perform it on all models or a particular content model type as applicable.

Different permission actions might require other actions to fully work, below is a table depicting these relations for mutations in particular:

Public API (read only)Anchor

A user may choose to expose all data in read only mode to be consumed via Public API, to do this one would have to go through the following steps:

1. Navigate to Project Settings, API Access, Public Content API.
2. Choose to create a new permission by pressing the Create Permission button.
3. In the Create Permission dialog, choose All for models and check Read, keep defaults of All for locales and stages and press the Create button.
4. The Public API should now be accessible with Read permissions.

Learn more about working with the Public API.

Permanent Auth Tokens (with specific models)Anchor

A Permanent Auth Token (PAT) can also be used to access content. The permission system allows to setup granular permissions for these tokens as well.

Let's assume that we would like to configure a PAT that allows to read and mutate only documents of a particular model type, the Post model from the Blog Starter template.

1. Navigate to Project Settings, API Access, Permanent Auth Tokens and press the Create Token button.
2. Fill in the new token name and optional description and press the Create & configure permissions button.
3. Under Content API in the given token's detail view, press the Create Permission button.
4. In the Create Permission dialog, choose the Post model and the Read, Create and Update actions keeping defaults for Locales, Stages and Condition and press the Create button.
5. You can now use this sample token to access Post documents, as well as creating them and updating them.

Note that with these basic settings it will not be possible to retrieve content for related models (ie: Author, Asset, SEO from the example).

To create posts and connect them to these other model types, specific permissions for those will need to be setup accordingly.

Learn more about authenticating with a PAT.

ConditionsAnchor

Custom conditions may be used to further limit the access to content. To build a condition, we recommend using the API playground to build a query with a where clause that would return the expected documents. Once this is done, the actual where clause can be stringified and used as a permission condition when creating a permission for the targeted model.

As a follow up example, we can further limit read access to the Post model by specifying conditions, here are some examples and what the result would be.

Grant access to posts that contain some tags in particular:

{ "tags_contains_some": ["GraphQL", "SEO"] }

Extend previous setting to also include posts that have no tags setup:

{ "OR": [{ "tags_contains_some": ["GraphQL", "SEO"] }, { "tags": null }] }

Setup access so that only the token can only manage Post documents that are related to a particular Author:

{ "author": { "id_in": ["ckadqgca800ix011230ailipe"] } }

Note that for this setup to work, read access on the Author model is required and could also be restricted to that particular document based on it's id for example.

{ "id": "ckadqgca800ix011230ailipe" }

Limits and considerationsAnchor

Total permissions per EnvironmentAnchor

At the moment, for the initial release of the feature, up to 50 custom permissions can be setup in a given project's environment in total.

The user may choose to use these as needed by distributing them across Public API, PATs and Custom Roles if applicable.

Learn more about working with Environments.

User system model & User attributionAnchor

Depending on what information needs to be exposed, the permissions might need to include read access to the User system model in order to display information related to content User Attribution.

This is specially important when setting up custom roles that will be interacting with the project's content via the UI, as User Attribution fields (createdBy, updatedBy and publishedBy) will not display this information if permissions are not granted. Another side effect of these permissions missing can translate into not allowed errors while trying to mutate content from the content view form.

Learn more about the system User model

Custom RolesAnchor

Custom roles have no permissions by default, as mentioned and in particular to work with the UI, they will need to be setup with Read access to the User system model as explained above and Read Versions for versioning to work as expected.

ConditionsAnchor

Conditions need to be manually kept up to date at the moment, this means that, for example, if a condition is based on a value for a given field, and the project's data model changes (ie: field is renamed) the condition sill no longer be valid. The same behavior is expected for related models and in cases were certain document ids are used for values.

Another aspect to consider regarding conditions is that although they can be created from a normal query where clause, they cannot be set for localized fields nor make use of search capabilities usually exposed as part of some inputs.

RelationsAnchor

When setting up permissions on models with relations, a 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 like the Post and Author, an update connecting a given Post with an Author will require also an update permissions on the Author model given that an Author can refer to many Post documents.

Learn more about relations.

LocalesAnchor

Permissions allow for a granular locale configuration. There are some important aspects to keep in mind when setting up permissions that would restrict access to certain actions on certain locales. In particular, in order perform actions on a base document (ie: create a new document with non localized fields), access to the default locale is required.