---
title: "Rotate an environment's host keys"
url: https://docs.corefinity.com/api/reference/access/rotate-ssh-host-keys
type: endpoint
last_updated: 2026-11-13
feature: ssh-keys
related:
  - https://docs.corefinity.com/guides/sites/access-and-security/ssh-keys.md
---
# Rotate an environment's host keys

Starts or moves on a host-key rotation of a CoreStack or CoreCluster environment: `stage` offers new host keys
beside the current ones, `finish` switches to them, `cancel` drops a staged rotation and `now` switches at
once, so every client then sees a changed host key. Type the environment's name in `confirm_environment`; an
environment takes six rotation steps an hour.

```http
POST /api/environments/{environment}/ssh/host-keys/rotation
```

- Scope: `write`
- Two-factor: required on your account (all)
- Rate limit: 30 an hour; 6 an hour for each environment
- Long-running: answers with an operation to poll
- Try it in the console: off. It overwrites data that cannot be brought back. Copy the request and run it yourself when you are sure.

## Path parameters

- `environment` (integer, required): The id of a CoreStack Enterprise environment. Not the same number as a site row id.

## Body

- `action` (string, required): `stage` offers new host keys beside the current ones. `finish` switches to the staged keys. `cancel` drops a staged rotation. `now` makes new keys and switches at once. One of `stage`, `now`, `finish`, `cancel`.
- `confirm_environment` (string, required): The environment's name, exactly as `GET /environments/{environment}/ssh` answers it.

## Request

### curl

```bash
curl -X POST https://manage.corefinity.com/api/environments/1311/ssh/host-keys/rotation \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "now",
    "confirm_environment": "Production"
  }'
```

### PHP

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->post('https://manage.corefinity.com/api/environments/1311/ssh/host-keys/rotation', [
        'action' => 'now',
        'confirm_environment' => 'Production',
    ]);

$data = $response->json();
```

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/environments/1311/ssh/host-keys/rotation', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action: 'now',
    confirm_environment: 'Production',
  }),
});

// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);
```

### Python

```python
import os
import requests

res = requests.post(
    "https://manage.corefinity.com/api/environments/1311/ssh/host-keys/rotation",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
    json={
        "action": "now",
        "confirm_environment": "Production",
    },
)

data = res.json() if res.content else None
```

## Responses

### 202 The rotation step was started. `rotation_id` is the rotation's id and `rotation` is the rotation as it stands. Follow it by reading `GET /environments/{environment}/ssh/host-keys` until `rotation.state` is `done`, `cancelled`, `aborted` or `failed` for the same `rotation.rotation_id`; a staged rotation waits in `offered` until it is finished or its day comes. `change_id` is always 0: a rotation is not a change that `GET /ssh/changes/{change}` answers.

```json
{
  "change_id": 0,
  "rotation": {
    "id": 3301,
    "last_error_public": null,
    "mode": "staged",
    "offered_at": "2026-11-06T09:20:00+00:00",
    "promote_after": "2026-11-13T09:20:00+00:00",
    "rotation_id": "hkr-0f1e2d3c4b5a",
    "state": "offered"
  },
  "rotation_id": "hkr-0f1e2d3c4b5a"
}
```

### 401 No token, or a token that is not valid.

```json
{
  "message": "Unauthenticated."
}
```

### 403 The token lacks the scope (`scope_required`, with the `scope` to use), or your company requires two-factor authentication and you have not set it up. For routes outside Managed Clusters.

```json
{
  "code": "company_unavailable",
  "message": "Your company is unavailable.",
  "reason": "company_unavailable"
}
```

### 404 The id does not exist or is something you cannot reach (`not_found`; both answer the same body), or SSH keys are not on for it (`feature_off`, which on a key change may add `field: null`).

```json
{
  "code": "feature_off",
  "message": "Not found.",
  "reason": "feature_off"
}
```

### 409 `stage` or `now` was asked while another rotation of this environment's host keys is still open (`ssh_rotation_in_progress`). Finish or cancel that one first.

```json
{
  "code": "ssh_rotation_in_progress",
  "field": null,
  "message": "A host-key rotation is already in progress.",
  "reason": "ssh_rotation_in_progress"
}
```

### 422 The request was refused. `reason` says why: `invalid_arguments` (a field is missing or wrong; `field` names it), `confirm_mismatch` (`confirm_environment` is not the environment's name), `ssh_host_keys_unmanaged` (the host keys of a CoreStack Enterprise environment are managed by Corefinity) or `ssh_rotation_unavailable` (host keys cannot be rotated here yet, there is no staged rotation to finish or cancel, the staged rotation is past the step that was asked, or the environment is not ready or is being moved; the message says which).

```json
{
  "code": "confirm_mismatch",
  "errors": {
    "confirm_environment": [
      "The name you typed is not this environment's name."
    ]
  },
  "field": "confirm_environment",
  "message": "The name you typed is not this environment's name.",
  "reason": "confirm_mismatch"
}
```

### 429 Too many requests: more than 30 rotation requests in an hour from you (`rate_limited`), or six rotation steps already taken for this environment in the last hour (`ssh_throttled`, with the wait in `retry_after_seconds` and no `Retry-After` header).

```json
{
  "code": "ssh_throttled",
  "field": null,
  "message": "Too many host-key rotations on this environment. Try again later.",
  "reason": "ssh_throttled",
  "retry_after": 1840,
  "retry_after_seconds": 1840
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 403 | `company_unavailable` | Your company is unavailable. |
| 403 | `scope_required` | Use a token with the scope named in `scope`. |
| 403 | `two_factor_required` | Turn on two-factor on your account, then send again. |
| 404 | `feature_off` | This feature is not on for your organisation yet. |
| 404 | `not_found` | Not found. |
| 409 | `ssh_rotation_in_progress` | A host-key rotation is already in progress. Wait for it to finish, or finish or cancel it. |
| 422 | `confirm_mismatch` | Send the confirmation exactly as the field named in `field` asks for it. |
| 422 | `invalid_arguments` | The arguments do not match the tool's input schema, or the Control Panel refused a field. Fix the fields named in the answer and call again. |
| 422 | `ssh_host_keys_unmanaged` | Host keys on this environment are managed by Corefinity. Nothing to rotate here. |
| 422 | `ssh_rotation_unavailable` | The environment cannot rotate its host keys now, or there is no staged rotation to finish or cancel. Read the host keys again. |
| 429 | `ssh_throttled` | Too many host-key rotations on this environment. Try again later. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |

## The same task elsewhere

- Guide: [SSH keys](https://docs.corefinity.com/guides/sites/access-and-security/ssh-keys.md)
