Was this page helpful?

Environment Alias

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

Currently, only one alias with the ID master is provided, and it cannot be renamed or deleted.

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), by using the alias ID in place of the environment ID.

For example, to get all entries from an aliased environment called release-1, use /spaces/<space-id>/environments/master/entries. This will implicitly request content from the release-1 environment.

Requests to spaces/<space-id>/entries without the environment alias fragment will have the same outcome.

For other operations through an environment alias, the same URL with and/or without the 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.

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.

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.