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

The managed key exists once an app or a CI environment is connected to the project (see
[Connect an app](connect-an-app.md)). 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

**Console**
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.

**CLI**
```sh
dcloud errors connections rotate-key project-id --grace-seconds 86400
```

**API**
```http
POST /errors/api/projects/project-id/rotate-key
{ "graceSeconds": 86400 }
```

`graceSeconds` is 600 (10 minutes) to 604 800 (7 days), 86 400 by default. The answer is `201` with
the new `dsn`, `revokeAfter`, `redeployed` (the apps rebuilding), `rebuildYourself` and `failed`.

## 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

**Console**
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.

**CLI**
```sh
dcloud errors connections revoke-previous-key project-id
dcloud errors connections extend-grace project-id --grace-seconds 172800
```

**API**
```http
POST /errors/api/projects/project-id/rotate-key/revoke-previous
```

```http
POST /errors/api/projects/project-id/rotate-key/extend
{ "graceSeconds": 172800 }
```

`extend` sets the earliest revocation to `graceSeconds` from now, earlier or later than before. It
still waits for the rebuilds and for the key to go quiet.

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

## Related

- [Connect an app](connect-an-app.md)
- [Manage DSN keys](manage-dsn-keys.md)
- `errors.connections.rotate-key` · `dcloud errors connections rotate-key`
