An environment alias allows you to access and modify the data of an environment, called the target environment, through a different static identifier.

A space admin must opt-in to this feature in the Contentful web app on the Settings > Environments page. During this opt-in process, we create a default alias with the ID master. This alias cannot be renamed or deleted. Once you've opted in, you can create up to two more aliases. Only space admins manage environment aliases.

Aliases and target environments can be used to enhance your development and deployment workflows. For example, you can safely apply content model changes and roll them back when necessary or use them in your CI/CD pipelines.

Requesting environment entities through aliases

You can request entities like assets, entries and locales through the environment alias (i.e. master or dev), by using the alias ID in place of the environment ID.

For example, if the master alias targets the release-1 environment, you can retrieve all entries from /spaces/<space-id>/environments/master/entries. This will implicitly request content from the release-1 environment.

Requests without an environment alias fragment will be treated like requests to the master environment alias. For example, requests to /spaces/<id>/entries will have the same outcome as requests to /spaces/<id>/environments/master/entries.

For other operations through an environment alias, the same URL with the environment alias fragment can be used.

Common uses for environment aliases

Enabling risk-free releases and instant rollbacks

Your master alias should be used to serve your “production” content. Use it to reference your most up-to-date, currently-used environment. All your apps can access this content by either specifically referencing /spaces/<space_id>/environments/master/content_types/... or leaving out the environment fragment alltogether: /spaces/<space_id>/content_types/….

Aliases empower you to quickly switch which environment is being served from these routes. Simply send a PUT request to re-target the master alias to a different environment. If something goes wrong and you need to roll it back, simply re-target master to any previous environment.

You can also create up to two more custom environment aliases. This can aid the development process. For example, you could create environment aliases dev and staging. Developers can always retrieve content from /spaces/<space_id>/environments/dev/..., but a space admin can re-target the dev environment alias to a different environment to test out a new content model.

Environment alias aware resources

All Environment aware resources can be interacted with through environment aliases.

Environment aliases and webhooks

Webhooks can be triggered for an environment alias using the filters property of a webhook just like environments. Webhooks only trigger for a given environment alias if it is used via that alias. Example: for a webhook set to trigger on the master environment alias only

• Sending a PUT spaces/<space-id>/entries/my-blog-post would trigger the webhook

• Sending a PUT spaces/<space-id>/environments/master/entries/my-blog-post would trigger the webhook

• Sending a PUT spaces/<space-id>/environments/environment-to-serve/entries/my-blog-post would not trigger the webhook

Please refer to the webhooks reference for more details.

You can also set up webhooks to fire on environment alias events. For example, when an alias is created, updated or deleted.

Environment aliases and API keys

You can select both environments and environment aliases that your API key will give you access to. Your API key configuration remains unchanged when you set up aliases in your space to use environment aliases.

Editorial workflow

It is recommended for editors to always work on the master alias.