Roles and permissions

This document explains how to use Roles and permissions – a feature which helps set up different access to content for different groups of users.

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.

• The guide: one writer, one translator, one editor
• Overview of the concepts
• How to manage roles

One writer, one translator, one editor: setting up a bilingual project with Contentful

Our research has identified several most common use cases for different roles:

• Making sure that the editor is the only person on the team who can publish content: she has to approve every bit of content before it becomes publicly available
• Making sure that writers can create content, but neither publish it nor delete it
• In case of multi-language projects: making sure that the translator can edit the content in the language they translate to, but never modify the source

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.

Prerequisites

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:

Creating the roles

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.

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: she can create, edit and open entries, and the rest – such as deleting and publishing – she cannot do.

Assigning the role

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 user+test1@domain.com.)

Click "…" on the right, proceed to "Change role", select the role from the list and assign it. That's all, really.

The Translator

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:

The Editor

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 she wants with the entries.

Testing it out

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.

List of entries, editor's view: she can create entries

List of entries, translator's view: she can't create entries, but can open the existing ones

Opened entry, editor's view: the "Publish" button is enabled

Opened entry, writer's view: the "Publish" button is disabled, as desired

Opened entry, translator's view: the Esperanto fields are editable, whereas the English ones are not

Next steps

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.

Overview of concepts: how R&Ps work

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.

Scope

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.

Roles

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.

Access rights

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.

• Action. The actions are:

1. Read
2. Create
3. Edit
4. Delete
5. (Un)Publish
6. (Un)Archive

• Content type. It's possible to give full access (everything allowed) to the content type "meal", but give zero access (can't even read) to the content type "drink".
• Creator. It's possible to enable opening only the content which the user has created themselves, and deny opening content created by other users.

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.

How to manage roles

Creating a new role

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.

Modifying an existing 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:

1. An action which can be one of "Read", "Create", "Edit", "Delete", "Publish/Unpublish", or "Archive/Unarchive".
2. A scope: either all entities, or only those created by the user themselves.
3. A content type such as "Post" or "Category".

When the action part of a rule is "Edit", there are 2 additional parts to allow for creating very fine-grained rules:

1. If the rule specifies a content type, it can be further narrowed to apply only to a specific field in that content type.
2. A locale, to allow or deny users permission to edit content in certain languages.

Explanation of different actions

There are 6 actions that can be restricted:

• Read: can users view these content items at all?

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.

• Edit: can users change this content?

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.

• Create: can users create new content?

This rule can be restricted to a particular content type, for example to allow users to create new posts but not new categories.

• Publish/Unpublish: can users publish or unpublish content?
• Archive/Unarchive: can users archive or unarchive this content?
• Delete: can users remove this content?

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.

Removing a role

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.

Assigning a role to a user

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.

Further reading

If you have any questions about roles and permissions, please take a look at the relevant FAQ section or talk to our support.