> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/_mcp/server.

Creating custom roles allows an administrator to restrict the access of users to certain resources. Roles follow an "allow list" approach, which means that you need to define everything a user is allowed to do. A role contains a name, description, permissions and policies.

Permissions can be basic rules which define whether a user can read or create content types, settings and entries.

The following permissions are supported:

| Permission           | Purpose                                                                                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Settings`           | Can modify space settings. This permission allows users to modify locales, webhooks, and the space name. It does *not* grant permission to update users roles or delete the space. |
| `ContentModel`       | Can modify content types (the content type builder is only shown to users who have this permission).                                                                               |
| `ContentDelivery`    | Can create and update API keys for this space                                                                                                                                      |
| `Environments`       | Can manage and use all environments in this space.  *Content level permissions do not apply in non-master environments.*                                                           |
| `EnvironmentAliases` | Can create environment aliases and change their target environment.                                                                                                                |
| `Tags`               | Can create and delete tags. (This does not control the ability to add/remove tags from entries and assets)                                                                         |

and each of those permission can have the following values:

| Value                   | Effect                                                                 |
| ----------------------- | ---------------------------------------------------------------------- |
| `null`, `[]`            | Disable the permission                                                 |
| `[ "read" ]`            | Allow only reading (*not* supported for `Settings` and `Environments`) |
| `[ "manage" ]`, `"all"` | Allow reading and writing                                              |

You can also create policies to allow or deny access to resources in fine-grained detail. With these polices you can, for example, limit read access to only entries of a specific content type or write access to only certain parts of an entry (e.g. a specific locale).

For information on how policies are specified, refer to the [programmatic role management guide](/tutorials/general/roles-via-api).

## Roles collection

[Get all roles](/references/content-management-api/roles/get-all-roles)

This endpoint returns a paginated list of roles for a given space. Each role contains a name, a description, permissions and policies, which describe what a user can and cannot do.

[Create a role](/references/content-management-api/roles/create-a-role)

Use this endpoint to create a custom role. The role name must be unique within the space.

## Role

[Get a role](/references/content-management-api/roles/get-a-role)

Use this endpoint to read an existing single role.

[Update a role](/references/content-management-api/roles/update-a-role)

Use this endpoint to update an existing role. You cannot use the endpoint to create a new role with a specific id.

[Delete a role](/references/content-management-api/roles/delete-a-role)

Use this endpoint to delete an existing role. You can only delete roles if there is no user in the space with *only* that role assigned, i.e. a user must have at least one role.


## API Docs

- Roles [Get all roles](https://contentful.com/developers/docs/references/content-management-api/roles/get-all-roles.md)
- Roles [Create a role](https://contentful.com/developers/docs/references/content-management-api/roles/create-a-role.md)
- Roles [Get a role](https://contentful.com/developers/docs/references/content-management-api/roles/get-a-role.md)
- Roles [Update a role](https://contentful.com/developers/docs/references/content-management-api/roles/update-a-role.md)
- Roles [Delete a role](https://contentful.com/developers/docs/references/content-management-api/roles/delete-a-role.md)

## OpenAPI Specification

The raw OpenAPI 3.1 specification for this API is available at:
- [OpenAPI JSON](https://contentful.com/developers/docs/openapi.json)
- [OpenAPI YAML](https://contentful.com/developers/docs/openapi.yaml)