This document explains how to use custom roles and permissions – a feature which helps set up different access to content for different groups of users. Custom roles do not apply to the on-demand tier, which have standard spaces that come with predefined roles.
We start with a quick how-to guide, showing a simple example and all the steps to get there, and then give a deeper overview of the concepts and workflows.
Before we dive in deeper, here is a summary of the four main roles:
Please note that Developer and Freelance roles have been deprecated in the current product version and are only available on select legacy plans.
Our research has identified several most common use cases for different roles:
In this example we'll create three different roles – editor, writer and translator – and set up appropriate access controls for each of them. We'll continue with the emojis example we've used previously, but now the content will be also translated into Esperanto.
We assume that you have a space with at least one content type, and with localization enabled for at least one field. In our example emoji is the content type, and title and description are the translateable fields. Here's the entire content model:
Click Settings at the top bar, and open Roles. This is where everything roles-related is set up. Note that you should be an Administrator or Owner of a space to be able to manage roles and permissions.
Administrator, Developer and Editor are the roles set up by default, and we're about to add some more. Let's start with the Writer.
Click "Create new role" on the right. Type some name (and possibly description) to help distinguish this role from others.
There are five sections below: entries, media library, content types, API keys and space settings. Individual content access can be set up for each section. The writer should deal only with entries, so for now that's the only section that's worth focusing on.
Click "Add a rule". There are three elements to each rule: the action(s), the owner, and the scope. Click on "All actions" to see all the available actions.
The writer should be able to do three things: creating the entries, edit them, and open them. (Contrary to what you might expect, each is a separate thing and has to be explicitly set up: that is, everything which is not explicitly allowed is denied.) We'll set up these three rules.
Select "Create" from the list and leave the rest as they are. Repeat the same for "Edit" and "Read". This is what you should end up with:
The access could be restricted further to specific content types or even specific fields within the content type, but that falls beyond the scope of this guide.
That's all for the writer: they can create, edit and open entries, and the rest – such as deleting and publishing – they can not do.
Go back to the list of the roles. The label next to the Writer role should read "0 members" – click it. You'll be redirected to the list of the users in this space. If you are the only one, it's just about time to invite some colleagues (or invite yourself with an email like
Click "…" on the right, proceed to "Change role", select the role from the list and assign it. That's all, really.
Go back to the list of the roles and create a new one. The translator should be able to view all the entries, but only edit content in the Esperanto language. Add two rules: one for Read, another for Edit. Instead of "All locales", the editing rule should be limited to only one language – select in the dropdown and you're done. Here's how it should look:
There is an editor role which comes by default – you can just open it and make sure that the editor is indeed able to do anything that they want with the entries.
For now the only way to make sure that the rules you set up have the effect you expect is to actually log in under each user and see how the interface looks.
Here is how the list of entries and one opened entry looks for different users.
The guide ends here. Hopefully, you've understood the basic principles of creating a role, setting up the rules specific for this role, and assigning the roles to the users.
We encourage you to experiment with different rules and see the effect they produce. Also, take a look at the more detailed explanations below.
Before setting up Roles and Permissions for your project, it's best to fully understand the core concepts behind them, so that you would be certain that you know what you're doing.
The access to content is managed separately and independently in each space: Jack can have full ownership of space A, but be just a proofreader in a space B.
First thing you need to do is to identify distinct roles specific to the project. These are roles that you would set up later. Different roles imply different level of access to content.
Here are some common examples of roles: writer, editor, translator, proofreader, photo editor.
For each role you would set up access to content individually. This is done by specifying what the user is allowed and not allowed to do. The access is specified by 1) action, 2) content type, 3) content creator.
The most important aspect is this: everything which is not explicitly allowed is denied. Here's an example: if you've enabled editing entries, but didn't enable reading them, then the user won't be able to open the entries. Even though it might feel counter-intuitive, this way of handling access rights helps preventing unsolicited access: when you set up everything explicitly, there is no chance of accidentally giving someone access to something they shouldn't have.
Select "Roles" from the "Settings" menu at the top of the screen (this menu is only available to space administrators). Find a role in the list that is similar to the role you'd like to create, click "…", and select "Duplicate role". On this new screen you can customize the rules that will apply to users who are assigned this role.
Select the "Roles" entry from the "Settings" menu at the top of the screen, find the role you wish to modify and click on its name. In this screen you can modify the roles permissions (simple check boxes such as "Can modify Content Types") as well as the roles policy (a list of rules that allow or deny various actions in various contexts).
The rules are split into two lists: one that says what the user is allowed to do, and a list of "exceptions": things a user will not be allowed to do even if the first list says they can. Each one of these rules applies to either entries or assets, and is made up of 3 parts:
When the action part of a rule is "Edit", there are 2 additional parts to allow for creating very fine-grained rules:
There are 6 actions that can be restricted:
Roles must be given explicit permission to read content items such as assets or entries. This means it's very possible to set up a role that is allowed to create or edit entries, but since they cannot read them, effectively won't be able to do anything. Items which a user does not have permission to read will be hidden in the entry list. When an entry the user can read contains a link to an item the user cannot read, they will be shown a warning the item either doesn't exist or can't be shown to them.
A user who cannot change content may still be able to see it, but in a read-only state. Editing can be restricted not only to content types, but also to individual fields or languages.
This rule can be restricted to a particular content type, for example to allow users to create new posts but not new categories.
Note that Contentful requires content to be unpublished before deletion. This means a role that can delete content but not unpublish will only be able to remove drafts.
Select the "Roles" entry from the "Settings" menu at the top of the screen (this menu is only available to space administrators). Find a role in the list that is similar to the role you'd like to create, click the "…" button and select "Delete role". If this role has been assigned to any users, you will be required to select a new role for them. Keep in mind that the administrator role cannot be removed.
Select the "Users" entry from the "Settings" menu at the top of the screen (this menu is only available to space administrators). Find the user you wish to assign a new role, click the "…" button and select "Change role". Select the new role you wish to assign the user to and confirm.
Note: it is possible to change your own role (and thus lose permissions to update roles any further). It is even possible make all users in a space non-administrators. If this happens and you wish to restore administrative privileges in the space, you can do so under your account settings.