General concepts > Project collaborators, roles and permissions

In addition to the account(s) owner of the project, who always enters the project with full privileges, it is also possible to invite further users to a project, giving them more refined permissions.

These additional users in DatoCMS are called Collaborators, and for them DatoCMS offers a thorough roles and permissions system to precisely specify what actions they can perform (ie., “read-only permission on every content, except for articles which can be freely created/updated but cannot be deleted or published online”).

The permissions given to a collaborator is managed separately and independently in each DatoCMS project: ie. Jack can have full privileges in project A, but can be just a proofreader in project B.

Default roles

Every DatoCMS project is automatically populated with the following roles, but you are free to create as many roles as you want, and assign them both to collaborators and API tokens:

• Admin: Can do everything, including work with records, create and update models, configure project settings and work with API keys.

• Editor: Can work with records, does not have access to models, API keys or project settings.

For each role, you can specify what the user is allowed and not allowed to do.

Project-wide permissions

Roles can grant/deny the ability to access and configure the project's administrative settings, including:

• Models, fields and navigation bar;

• Project's languages, deployment, time zones and SSO settings;

• Roles and invite/remove collaborators;

• Webhooks;

• API tokens;

• Shared filters.

Control access to environments

Roles specify access-level permissions to environments. You can allow users to access:

• All environments (useful for developers)

• Only the primary environment (useful for content editors)

• Only the sandbox environments (mostly useful for API tokens used in CI systems)

This setting is very useful because it allows you to pre-configure the content-level permissions (which records a user can create/update/delete/etc.) on sandbox environments without letting editors actually enter the environment and make changes until it gets promoted to primary.

In other words, the permission to access the environments takes precedence over the content-level permissions set inside a specific environment!

Content-level permissions

For each environment, you can specify different permissions on actions that can be performed on records. Rules can be additive or subtractive, and are defined by:

• The action:

  • View

  • Create/duplicate

  • Edit

  • Publish/unpublish

  • Delete

  • Take over

  • Move to stage (for workflows)

• The model: i.e., it's possible to give full access (everything allowed) to the model meal, but give zero access (can't even read) to the model drink.

• The creator: i.e., it's possible to edit only the content which the user has created themselves (or users with its same role), and deny opening content created by other users.

The most important aspect is that everything which is not explicitly allowed is denied. Here's an example: if you've granted a user the permission to edit some records, you also need to give them permissions to view them, or they won't be able to open the record and make the changes.

Even though it might feel counter-intuitive, this way of handling access rights helps to prevent unsolicited access: when you set up everything explicitly, there is no chance of accidentally giving someone access to something they shouldn't have.

Translator role, and locales permissions

On an Enterprise plan, your project and models can have locale-specific permissions. For each translator role, you can define the specific locale(s) they have access to, limiting their ability to view/add/edit/remove records to just those languages. This can be applied either globally across your whole project, or more granularly defined on a per-model basis.

Need locale-specific permissions? Talk to our Sales team about an Enterprise plan.

Workflows permissions

If some of your models are under a Workflow, you can also define which actions are allowed depending on the specific stage a record is in. You can learn more in the appropriate section of the documentation.

Forking the environments

When forking an environment, for each existing role, DatoCMS duplicates the content-level permissions you had on the original environment to the copy.

Asset permissions

Together with the actions that you can perform on the records, similarly you can apply the following permissions on assets:

• The action:

  • View

  • Create/duplicate

  • Edit metadata/replace asset

  • Delete

  • Edit creator

• The creator: i.e., it's possible to edit only the assets which the user has created themselves (or users with its same role), and deny using assets created by other users.

Putting everything together with an example

To better exemplify, let’s consider a project that:

• has only one environment (the primary one), and

• has a Blog Editor role that:

  • Access-level permission: only gives access to the primary environment, and...

  • Content-level permission: …only allows to manage records of type article.

If I fork the primary environment to a new one called foobar, the content-level permissions get duplicated (that is, blog editors can only manage records of type article also inside the foobar environment). But they will only be able to do so when the foobar environment gets promoted to primary, since the access-level permission doesn't give them access to sandbox environments.

This allows to safely test and experiment changes to permissions on the roles without affecting the work of your collaborators on the primary environment, and without giving them privileges to edit sandbox environments.

Roles inheritance

As your project grows and evolves, permissions on each role can become quite complex. To allow greater modularity, simplicity and clarity, you can organize your roles in hierarchies. In this way, users with greater rights automatically inherit all the permissions of roles lower in the hierarchy, without having to duplicate permissions assignments for multiple different roles.

You can configure the hierarchy using the “Inherits permissions from” field in the Edit role form:

Learn more about roles and permissions

Get a hands-on learning experience with our tutorial videos:

Intro to Settings & Configurations

Play video »

Using Roles for Content Governance

Play video »