Rotate the managed key

Replace the DSN key that connected apps and CI environments use, rebuild every connected app with the new one, and retire the old key once nothing sends with it.

Last updated 18 November 2026View as Markdown

The managed key exists once an app or a CI environment is connected to the project (see Connect an app). Rotating it never touches the project's other keys. Replace project-id with the project's id.

Prerequisites

  • Permission for errors:UpdateProject on the project.
  • In the console, also errors:ListProjects on the project to open it (without it the project is not found).
  • A rotation starts a rebuild of every connected app; each rebuild is a deployment of that app.

Rotate the key

  1. Open the project, then the Setup tab.
  2. Under Managed key, for Previous key works for at least, choose 1 hour, 24 hours (default) or 7 days.
  3. Choose Rotate key, then confirm with Rotate key.

The console says how many apps are rebuilding, which to rebuild yourself, and which rebuilds could not start.

What happens

  1. A new key is created. The managed entry in Secrets gets a new version holding its DSN.
  2. Every connected app is rebuilt and redeployed, so the new DSN also reaches its browser bundle.
  3. The previous key keeps accepting events. It is revoked once all of these hold:
    • the grace is over;
    • every connected app built here runs a deployment made after the rotation (a rebuild that failed holds the revocation);
    • the previous key has received no event for 15 minutes.

Apps that run an image or a compose file built elsewhere get the new DSN at run time, but their browser bundles keep the old one until you rebuild them; the rotation lists them under rebuildYourself, and does not wait for them.

While a rotation is in progress, the Setup tab says "A rotation is in progress." with the earliest time the previous key is revoked, and offers no Rotate key until it is revoked.

End the grace early or move it

  1. Open the project, then the Setup tab.
  2. Under Managed key, choose Revoke previous key now.

The previous key is revoked at once; events still sent with it are refused.

When a rotation is refused

  • 404 "Nothing is connected to this project, so there is no managed key".
  • 409 "A rotation is still in its grace period: revoke the previous key now, or wait until it is revoked".
  • 409 "No rotation is in progress" for revoking or extending when there is none.
Did this page help you?