Was this page helpful?

Environment Alias

What is an environment alias?

Environment alias is a static ID that allows you to access and modify the data of its selected target environment. The environment alias target can be quickly switched to a different environment.

The first environment alias that is set up in a space, is granted a default ID “master”.

The “master” alias can’t be deleted and its ID can’t be changed.

Premium/Enterprise customers can create custom aliases, in addition to the “master” alias.

Environment 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.

To learn how to create an environment alias, refer to Create an environment alias.

Request environment entities through aliases

You can request entities like assets, entries and locales through the environment alias by using the alias ID in place of the environment ID.

Below is an example of how to request entities belonging to a specific environment through an environment alias:

Let’s assume we need to retrieve all entries from an environment with ID release-1 that is targeted by an environment alias with ID master In the request, we replace the environment ID with the alias ID:


Running the command above implicitly requests content from the release-1 environment.

Requests without an environment alias fragment will be treated like requests to the "master" alias (or "master" environment if environment alias isn't enabled. For example, requests to /spaces//entries will have the same outcome as requests to /spaces//environments/master/entries.

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. For example, your webhook is set to trigger on the master environment alias only. To trigger the webhook, send a request according to one of the following options:

  • PUT spaces/<space-id>/environments/master/entries/my-blog-post
  • PUT spaces/<space-id>/entries/my-blog-post

For the same webhook, sending the following request doesn’t trigger the webhook:

PUT spaces/<space-id>/environments/environment-to-serve/entries/my-blog-post

Please check the webhooks API 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 in the "master" alias.

To learn more about how to use environments and environment aliases, refer to Environments and environments aliases best practices.