> 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/developers/docs/_mcp/server. # Managing access to environments > This guide explains how to use custom roles to restrict access to environments and aliases to secure, simplify, and speed up the development process. Space Administrators can tightly control who has access to environments and aliases, thereby securing, simplifying and speeding up the development process. This guide explains which levels of access to environments can be provided with a custom role and gives guidance and tips on how to set up fine grained environment access restrictions. * [Master environment only](#master-environment-only) * [Selected environments](#selected-environments) * [Manage and use all environments](#manage-and-use-all-environments) ## Options overview Customers on Premium/Enterprise plans can create custom roles that allow them to define access to environments and environment aliases according to the following options: ### Master environment only A role with this permission can only access entities inside the master environment or the target environment of the master alias. Content level permissions (e.g. restrictions on which entries, assets or content types can be edited) apply to the master environment. This is the default and most restrictive option. It should be used for all roles which don't interact at all with environments, e.g. editors. ### Selected environments This option allows you to select specific environments and environment aliases that a given role can access. Content level permissions apply in all specified environments and aliases, but creation or deletion of environments or aliases is not allowed. This option can be useful for different scenarios - for example, for editors who need to edit content on distinct non-master environments or QA engineers who need access to staging and master environments only. ### Manage and use all environments A role with "Manage and use all environments" permission has full CRUD (create, read, update and delete) rights for all environments in the space. This role has full access to all content in sandbox environments. In the master environment or the target environment of the [master alias](/concepts/environment-aliases), the role's access to content is defined by its content and media permissions. > **Info** > > A space Administrator role has full access to all environments (including the master environment) and their content. This is the least restrictive option. It is recommended for developers who need to not only access entities inside of environments as part of their workflow, but also create and delete environments. > **Info** > > For more information on how to use environments, please refer to [Multiple environments](/concepts/multiple-environments). ## Access to environments endpoints A role's access to environments applies only to the entities contained in environments. A user is able to access environments and environment aliases endpoints irrespective of the selected access to environments option. When a user sends an API request to [get all environments within a space](/references/content-management-api/environments/get-all-environments-of-a-space), the full list of the existing environments is returned, including those that the user's role is not allowed to access. > **Info** > > For security reasons, we recommend that you do not include any confidential information in any environment's name, as the environments' names are visible to all users within a space. ## Access to the target environment of the master alias Access to the target environment of the master alias is defined via the master alias ID, and not via the ID of the target environment. To better explain how to grant your role access to the target environment of the master alias, let's consider the following example: Let's assume you have a master alias and two sandbox environments - `production` and `staging`. `production` is selected as a target environment for your master alias. Now, for your space role to be able to access `production` environment, grant this role access to `master`. If you later change your master alias target environment to `staging`, the role will lose access to `production` and will be granted access to `staging`. Conversely, to deny a role access to an environment which is targeted by the master alias, make sure the role does not have access to `master`. ## Environment permissions override environment policies In the API, "Manage and use all environments" and "Selected environments" options are referred to as environment `permissions` and environment `policies`, accordingly. We do not recommend enabling both options in the same role, because in this case environment `policies` are not validated, and environment `permissions` override environment policies. As a result, the role will be allowed to access and manage all environments in a space. An example role definition below contains environment `policies` which target specific environment IDs, but has unrestricted access to all environments due to the existence of an environment `permissions`: ```javascript { "name": "Role with environment permission and environment policies", "permissions": { "Environments": "all" }, "policies": [ { "effect": "allow", "constraint": { "and": [ { "equals": [ { "doc": "sys.type" }, "Environment" ] }, { "equals": [ { "doc": "sys.id" }, "staging" ] } ] }, "actions": [ "access" ] } ] } ``` > **Info** > > To learn how environment permissions combine when multiple roles are assigned to a single user, please refer to [Assigning multiple environment access options to a single user](https://www.contentful.com/help/environments-permissions/#assigning-multiple-environment-access-options-to-a-single-user). ## How to set up a role with access to selected environments in the web app In the example below, we create a role for an editor to grant them access to `master` and `staging` environments. Full CRUD rights for entries and read-only rights for assets are enforced in both environments. The role is created via the web app. To create a role with access to `master` and `staging` environments: 1. Navigate to the **Settings** tab and click on **Roles & permissions**. Click **Create a new role**. 2. Add a name and a description for your role. 3. Go to the **Environments** tab. ![Manage access to environments tutorial 1 image](/developers/docs/_fern-img/e963cd93f18f4118e504de1aeadce5504dc7aff4668fc75d2b7d5645ddbb2a3d.webp) 4. Under the **Access to environments** area, select the **Selected environments** option. 5. Under the **Allowed environments** area, add the environments and environment aliases you want to grant access to. In our example, the role is granted access to a `master` alias that points to a target environment `production` and to the `staging` environment. ![Manage access to environments tutorial 2 image](/developers/docs/_fern-img/90a79076f235e7ee33c1213d88123253a65745177ed70c359ecfbf67ef4a7341.webp) 6. Go to the **Content** tab and set the rules to define access to content in the selected environments. In our example, we allow all CRUD actions for entries of any content type. ![Manage access to environments tutorial 3 image](/developers/docs/_fern-img/e9233a915106e3697b85510f4e000e5f65be9618fe385e89a91992488b005806.webp) 7. Go to the **Media** tab and set the rules to define access to media in the selected environments. In our example, we allow read-only access to all assets. ![Manage access to environments tutorial 4 image](/developers/docs/_fern-img/ebc695403c517b1b16aeb3d4ef32f058f7f6382364e36dd9414cd815a8ed26f5.webp) > **Info** > > The role editor allows you to set rules based on tags, content types and entries only from your master environment. You can configure rules for tags, content types and entries from your sandbox environments via the [API](/tutorials/general/managing-access-to-environments#how-to-set-up-a-role-with-access-to-selected-environments-via-api). 8. Click **Save changes** to save your role. > **Info** > > For more information on how to set up access to environments via the web app, please refer to [Environments permissions](https://www.contentful.com/help/environments-permissions/). ## How to set up a role with access to selected environments via API You can also set up your roles programmatically. In the example below, we create a role with the same access restrictions as set in our [example of setting up a role in the web app](/tutorials/general/managing-access-to-environments#how-to-set-up-a-role-with-access-to-selected-environments-in-the-web-app). **Endpoint: \[POST] /spaces/\{\{ spaceId }}/roles** **Base URL:** [https://api.contentful.com](https://api.contentful.com) **Description:** This endpoint is used to create a custom role. **Response:** ```javascript { "name": "Editor with staging access", "description": "Editor with staging access", "policies": [ { "effect": "allow", "constraint": { "and": [ { "equals": [ { "doc": "sys.type" }, "Entry" ] } ] }, "actions": "all" }, { "effect": "allow", "constraint": { "and": [ { "equals": [ { "doc": "sys.type" }, "Asset" ] } ] }, "actions": [ "read" ] }, { "effect": "allow", "constraint": { "and": [ { "equals": [ { "doc": "sys.type" }, "Environment" ] }, { "equals": [ { "doc": "sys.id" }, "master" ] } ] }, "actions": [ "access" ] }, { "effect": "allow", "constraint": { "and": [ { "equals": [ { "doc": "sys.type" }, "Environment" ] }, { "equals": [ { "doc": "sys.id" }, "staging" ] } ] }, "actions": [ "access" ] } ] } ``` > **Info** > > Note that if a role is defined via API, it might have a format that is not supported by the UI. > **Info** > > For more information on how to manage roles programmatically in general see also [Managing Roles - programmatically](/tutorials/general/roles-via-api). ## Next steps * [Merge content with contentful-merge](/tutorials/general/diff-and-merge-content-with-contentful-merge)