Was this page helpful?

Managing Roles - programmatically

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",
    "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:

Name Keyword Description and Use cases
AndConstraint and The AndConstraint evaluates if all its conditions are true. The value of the AndConstraint needs to be an array with an arbitrary amount of constraints.
The AndConstraint is necessary and useful for a broad variety of use cases. An example of the constraint is the limitation to a specific content type:
{ 
"and": [
{ "equals": [{ "doc": "sys.type" }, "Entry"] },
{ "equals": [{ "doc": "sys.contentType.sys.id" },
"content-type-id"] }
]
}
NotConstraint not The NotConstraint inverts the result of its value. The value of the OrConstraint must be another constraint. A typical use case for the NotConstraint is the inversion of whitelists to blacklist.
For example, to disable a user from not being able to see entries of a specific content type, it can either be achieved by denying access to those content types or by allowing access to all but the entries of the content type:
{
"and":[
{ "equals": [{ "doc": "sys.type" }, "Entry"] },
{ "not": { "equals": [{ "doc": "sys.contentType.sys.id" },
"content-type-id"] } }
]
}
OrConstraint or The OrConstaint evaluates if one if its conditions returns true. The value of the OrConstraint needs to be an array with an arbitrary amount of constraints.
OrConstraints are used to enable an effect for various different resources. For example, if a user is only allowed to read entries of a specific content type or all assets:
{
"or": [
{"and": [
{ "equals": [{ "doc": "sys.type" }, "Entry"] },
{ "not": { "equals": [{ "doc": "sys.contentType.sys.id" },
"content-type-id"] } }
]},
{ "equals": [{ "doc": "sys.type" }, "Asset"] }
]
}
EqualityConstraint equals The EqualityConstraint can be used to compare an entity's field or metadata against a specific value.
EqualityConstraints are one of the very basic constraints and are typically used to ensure the type of a document or to match entries of a content type.

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'.

Next steps

Not what you’re looking for? Try our FAQ.