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
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: /
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
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
PUT spaces/<space-id>/entries/my-blog-postwould trigger the webhook
PUT spaces/<space-id>/environments/master/entries/my-blog-postwould trigger the webhook
PUT spaces/<space-id>/environments/environment-to-serve/entries/my-blog-postwould 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.
It is recommended for editors to always work on the master alias.