Roles

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.

Roles collection

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

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

Role

Get a role

Use this endpoint to read an existing single role.

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

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.