What are Custom Roles?

Custom roles allow the administrator to restrict access of users to certain resources. Roles follow a whitelisting approach, wherein everything that a user is allowed to do, needs to be explicitly defined.

Along with a name and description, a role contains, permissions and policies. Permissions are basic rules that define whether (or not) a user can access content types, settings, and entries. It can be specified if a user can read and/or manage those.

On the other hand, there are policies that are used to allow or deny access to resources in a very fine-grained fashion. For example, with policies it is possible to limit read access to only entries of a specific content type or write access to only certain parts of an entry (e.g. for a specific locale).

Note: A role name must be unique within the space.

Create a Role

Endpoint: [POST] /spaces/{{ spaceId }}/roles

Base URL: https://api.contentful.com

Description: This endpoint is used to create a custom role.

Response:

{
  "sys": {
    "type": "Role",
    "id": "0xvkNW6WdQ8JkWlWZ8BC4x",
    "version": 0,
    "createdAt": "2015-05-18T11:29:46.809Z",
    "createdBy": {
      "sys": {
        "type": "Link",
        "linkType": "User",
        "id": "7BslKh9TdKGOK41VmLDjFZ"
      }
    },
    "updatedAt": "2015-05-18T11:29:46.809Z",
    "updatedBy": {
      "sys": {
        "type": "Link",
        "linkType": "User",
        "id": "4FLrUHftHW3v2BLi9fzfjU"
      }
    }
  },
  "name": "Some role",
  "description": "Test role",
  "permissions": {
    "ContentModel": [
      "read"
    ],
    "ContentDelivery": "all",
    "Environments": "all",
    "EnvironmentAliases": "all",
    "Settings": "all"
  },
  "policies": [
    {
      "effect": "allow",
      "actions": [
        "read",
        "create",
        "update",
        "delete",
        "publish",
        "unpublish",
        "archive",
        "unarchive"
      ],
      "constraint": {
        "equals": [
          {
            "doc": "sys.type"
          },
          "Entry"
        ]
      }
    }
  ]
}

To enable all the permissions pertaining to a role, use the "all" keyword. It enables all possible values for the respective permission.

{
  "name": "Name of the role",
  "description": "Description of the role",
  "permissions": {
    "ContentDelivery": "all"
    "ContentModel": "all",
    "Settings": "all"
  },
  "policies": [
    {"effect": "allow", "actions": "all"}
  ]
}

Instead of "all", it is possible to define an array of allowed actions, thereby providing partial access to the system.

{
  "name": "Name of the role",
  "description": "Description of the role",
  "permissions": {
    "ContentDelivery": [
      "read", // Allows reading of api keys
      "manage" // Allows creation/deletion of api keys
    ],
    "ContentModel": [
      "read", // Allows reading of content types. Note that you cannot read entries without reading content types.
      "manage" // Allows creation/manipulation/deletion of content types
    ],
    "Settings": [
      "manage" // Allows full access to the settings section in the web UI
    ]
  },
  "policies": [
    {"effect": "allow", "actions": "all"}
  ]
}

Constraints

Constraints are fine-granular and content-focussed access rules defined with the role's policies. For example,

{
  "name": "Name of the role",
  "description": "Description of the role",
  "permissions": { "ContentDelivery": "all", "ContentModel": "all", "Settings": "all" },
  "policies": [
    {
      "effect": "allow", // With "allow" we are enabling a user to do certain things.
      "actions": "all"   // The keyword "all" is an alias for ['read', 'create', 'update', 'delete', 'archive', 'unarchive', 'publish', 'unpublish'],
      "constraint": {    // A constraint can be defined to restrict the effect and the actions to a subset of entities.
        <ConstraintKeyword>: <ConstraintValue>
      }
    }
  ]
}

The following table lists and explains the supported constraints:

{ 
 "and": [
   { "equals": [{ "doc": "sys.type" }, "Entry"] },
   { "equals": [{ "doc": "sys.contentType.sys.id" },
    "content-type-id"] } 
  ] 
}

{
 "and":[
   { "equals": [{ "doc": "sys.type" }, "Entry"] },
   { "not": { "equals": [{ "doc": "sys.contentType.sys.id" },
     "content-type-id"] } }
   ]
}

{
 "or": [
  {"and": [
   { "equals": [{ "doc": "sys.type" }, "Entry"] },
   { "not": { "equals": [{ "doc": "sys.contentType.sys.id" },
    "content-type-id"] } }
   ]},
   { "equals": [{ "doc": "sys.type" }, "Asset"] }
 ]
}

Update a Role

Endpoint: PUT /spaces/{{ spaceId }}/roles/{{ roleId }}

Base URL: https://api.contentful.com

Description: This endpoint is used to update an existing custom role. This endpoint can also be used to create a new role with a specific id.

Response:

{
  "sys":{
    "type":"Role",
    "id":"48x6PYyasXaAuN3kQgposV",
    "version":0,
    "space":{
      "sys":{
        "type":"Link",
        "linkType":"Space",
        "id":"296guvxfpn71"
      }
    },
    "createdBy":{...},
    "createdAt":"2013-07-04T13:06:57Z",
    "updatedBy":{...},
    "updatedAt":"2013-07-04T13:06:57Z"
  },
  "name":"Editor",
  "description":"Allows editing of all Entries",
  "policies":[
    {
      "effect":"allow",
      "actions":"all"
    }
  ],
  "permissions":{
    "ContentModel":[
      "read"
    ],
    "Settings":[],
    "ContentDelivery":[]
  }
}

It is possible to apply the constraints while updating a role.

Delete a Role

Endpoint: PUT /spaces/{{ spaceId }}/roles/{{ roleId }}

Base URL: https://api.contentful.com

Description: This endpoint is used to delete an existing custom role. It is not possible to delete a role, if the user corresponding to this role does not have any other assigned roles.

Response: The server responds with a http code '204' in case of successful deletion of the role. If the user is assigned only with the role that is to deleted, the server responds with a http code '412'.