Custom roles and permissions

What is a space role?

Space roles are sets of predefined permissions that can be assigned to users within a space. Typically they are used to restrict or allow access to certain content areas. Keep in mind that roles make sense only within spaces, not throughout the entire platform.

A user can have different roles in different spaces. In most plans, Contentful comes with three predefined roles: editor, developer, and administrator.

• Editors can only add entries to already defined content types and assets. They cannot access other parts of the space, such as content model and API keys, or change the space settings.
• Developers can only read entries and manage API Keys.
• Administrators have access to the whole space, including the content model and space settings.

Our enterprise plans allow you to customize the roles in each of your spaces.

Can a user have more than one role in a space?

No, each user can only have one role per space. However, a user can have a different role in each space, and each role can be assigned to multiple users.

How do I create and assign roles?

Under your Space Settings, select 'Roles'. Here you will see a list of the existing roles and how many members are assigned to each role. Click 'Create new role' on the right sidebar, define the role's permissions and exceptions, then hit 'Save changes'.

To assign a user to a role, you can either navigate to the 'Users' page (under your Space Settings) or simply click on the number of members to the right of the role name. For existing Space members, click on the '…' and select 'Change role'. Otherwise click the 'Invite new users to this space' button in the sidebar and select the role from the dropdown menu.

You can also create and define custom roles via our Content Management API.

How can I use custom roles?

Custom roles allow you to create arbitrary rule sets & restrictions for groups of users in your space. Some examples of custom roles are:

• A designer role that can only edit entries that control the visual aspects of a site.
• An author role that can create "Post" entries but not publish or unpublish them. This is useful for preventing accidents in larger teams where only certain editors should be able to make content "go live".
• A translator role that can edit content only in one specific locale (language) but cannot publish.
• An editor role that can publish any content except for the visual settings managed by the design team.

What permissions can I define with custom roles?

Our enterprise plans allow you to define custom space roles with entirely customized sets of permissions. These permissions are defined as a list of things a user is allowed to do, and a list of "exceptions": things a user will not be allowed to do. Each one of these permissions or exceptions applies to either entries or assets, and is made up of 3 parts:

1. An action such as "Read", "Edit" or "Delete".
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 parameters that let you create fine-grained rules:

1. A locale, to allow for users that can only edit content in specified locales.
2. When an edit rule specifies a content type, you can further limit it specific fields in that content type.

What actions can I restrict with custom permissions?

There are 6 actions that can be restricted:

Read: can users view these content items at all?

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 "Post" entries but not new "Category" entries.

Publish/Unpublish: can users publish or unpublish content?

When a user cannot publish content, the green 'publish' button will be grayed and unclickable. The entry will remain as a draft until a user with permission to publish comes along.

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.

Can I define permissions on a per-item basis?

Currently it's not possible to define permissions on an individual entry or asset.