1. Manage an environment

Rotate Deploy secrets for your environments

SitecoreAI environments use several secrets and tokens to securely connect services such as editing hosts, Edge, and Page builder. Rotating these secrets helps reduce the risk of credential leakage, limits the impact of compromised tokens, and supports security and compliance best practices. Regular secret rotation is also recommended when access scopes change, external editing hosts are updated, or as part of routine operational hygiene.

This topic explains how to rotate secrets for a SitecoreAI environment by regenerating the required keys and tokens through the SitecoreAI Web API. The procedure demonstrates how to use the built-in Swagger UI, but you can use any other API client or automation approach that fits your workflow. The process includes regenerating environment secrets, redeploying the environment, and updating any external Editing hosts to ensure uninterrupted authoring and page editing experiences.

Warning

This is a time-sensitive, multi-step process that must be completed in order:

  1. Regenerate the editing secret.
  2. Regenerate the Edge token. ​This invalidates the Context IDs, so proceed immediately with the next step.​​
  3. Regenerate Context IDs.
  4. Update live websites with new live Context ID / scoped Context IDs.
  5. Redeploy the SitecoreAI environment.
  6. Update any existing external editing hosts with new preview Context ID and editing secret. We recommend testing this procedure in a lower environment first. When working in production, run this procedure outside of regular working hours.

Prerequisites

Secret rotation and environment regeneration are restricted to users who can manage and redeploy SitecoreAI environments. Make sure you have access to the SitecoreAI Deploy app, and that you have the Organization Admin role. ​ To create a rotation of secrets for environments, you must first obtain your current user access token and the environment ID. ​ To obtain a user access token:

  1. In Sitecore Cloud Portal, in the top right corner, click the ​Profile​ icon > ​System information​​.
  2. In the dialog that opens, copy the Bearer token, and paste it on a note for later use. ​
Note

The token is valid for 15 minutes. To obtain a new token, reload the page.

To obtain the environment ID:

  1. In SitecoreAI Deploy, click the relevant project name, then click the environment name where the secrets rotation is required.
  2. On the authoring environment's ​Details​ tab, copy the ​Environment ID​​ and paste it on a note for later use.

Create the secret rotation

This is a time-sensitive, multi-steps process that must be completed in order:

  • Regenerate the editing secret.
  • Regenerate the Edge token. This invalidates the Live Context ID, so proceed immediately with the next step.
  • Regenerate Context IDs.
  • Update the Context IDs in all live sites and any external editing hosts. Also redeploy your sites to update the internal editing hosts. ​ To create the secret rotation:
  1. Open the ​Swagger UI​​ page.
  2. Click ​Authorize​​.
  3. In the ​Available authorizations​ dialog, in the ​Value​ field, enter the ​Bearer token value​​ you saved earlier.
  4. Click ​Authorize​​, then close the dialog.
  5. To regenerate the editing secret:
    1. Open the ​Renerate-editing-secret​ endpoint, then click ​Try it out​​.
    2. In the EenvironmentId​ field, enter the ​environment ID​ you saved earlier, and click ​Execute​​.
    3. Validate that the response code is 200, then copy the value from the ​Reponse body​​ and save it on a note for later use in cases where the environment has externally configured editing hosts.
  6. To regenerate the Edge token:
    1. Open the ​Renerate-edge-token​ endpoint, then click ​Try it out​​.
    2. In the EnvironmentId​ field, enter the ​environment ID​ you saved earlier, and click ​Execute​​.
    3. Validate that the response code is 202. If you have externally configured rendering host instances, copy and save the value from ​apiKey​​ property, as it will be needed later on.
  7. To regenerate Contexts ID, in the Deploy app, on the ​Details​ page of the environment, click ​Regenerate​​. You can then copy the new ​Context ID Live​ and ​Context ID Preview​​ and paste them on a note for later use.
    Warning

    Revalidating the Edge Token invalidates all existing Context IDs. To keep the disruption time as short as possible, update the live Context ID on every live website immediately.

  8. To ​redeploy​ the environment, on the ​Deployments​ tab, click ​Options​ > ​Build and deploy​​.
  9. If your environment has external editing hosts configured, you must replace the revoked Context IDs with the replacement ones:
    • ​​SITECORE_EDGE_CONTEXT_ID​​ - Update with the new Preview Context ID value.
    • ​​NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID​ - Update with the new Preview Context ID value. For client-side use, a ​scoped context​​ should be created.
    • ​SITECORE_EDITING_SECRET​​ - Update with the value obtained from the Regenerate Editing Secret step.
  10. For all live websites (all ​rendering hosts​​), update with the new Live Context ID value. For client side use, a scoped context​ should be created.
  11. If you have previously created Scoped Context IDs, you must ​update​​ them too.
  12. Additionally, if you have external rendering hosts, you need to update ​SITECORE_API_KEY​​ ​environment variable ​​with the value from the Regenerate Edge Token step.
If you have suggestions for improving this article, let us know!