---
title: "Rotate an SSH key"
url: https://docs.corefinity.com/api/recipes/rotate-an-ssh-key
type: page
last_updated: 2026-11-13
feature: recipe-rotate-an-ssh-key
---
# Rotate an SSH key

Add a new SSH key of your own, check it is applied and remove the old one.

Rotating a key means adding the new one, checking it works and removing the old one, in that order, so you are never without a key. This recipe rotates Eleanor Finch's own key.

## Before you start

- A token with the `read` and `write` [scopes](/api/scopes).
- A new key pair made on your own machine. Only the public key is sent; a private key is refused and never stored.
- Steps 2 and 5 need [two-factor enrolment](/api/two-factor) when your company requires it.
- No step waits for a maintenance window.

1. **Read your keys**

   Note your `user_id`, and the `id` and `fingerprint` of the key to replace.

   ```bash
   curl https://manage.corefinity.com/api/user/ssh \
     -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json"
   ```

2. **Add the new key**

   Send the public key with a name to recognise it by. For a key of your own, `owner` is `user` with your `user_id`.

   ```bash
   curl -X POST https://manage.corefinity.com/api/ssh/keys \
     -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"owner": {"type": "user", "id": 2041}, "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAAAExampleKeyOnlyDoNotUseThisIsNotARealKey1 eleanor@laptop", "name": "Laptop, November 2026"}'
   ```

   The answer is `201` with the key and a `change_id` to follow. Note `key.id` and `change_id`.

3. **Follow the change**

   Adding a key answers a change, not an operation. Read it every few seconds until its `state` is `applied` or `failed`; `failed` lists the environments that did not take it.

   ```bash
   curl https://manage.corefinity.com/api/ssh/changes/5184 \
     -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json"
   ```

4. **Check the new key**

   Read your keys again. The new key's `delivery.state` is `applied`, and `reach` lists each environment with the `command` that signs you in.

   Sign in with the new key before you remove the old one.

   ```bash
   curl https://manage.corefinity.com/api/user/ssh \
     -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json"
   ```

5. **Remove the old key**

   Send the old key's fingerprint, exactly as step 1 answered it, as `confirm_fingerprint`.

   > **Warning:** This deletes the old key from your keys: it stops working on every environment it reached through you. `remaining_sources` in the answer lists the places the same key is still held, such as a company key.

   ```bash
   curl -X DELETE https://manage.corefinity.com/api/ssh/keys/6204 \
     -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"confirm_fingerprint": "SHA256:o6poLLVqPDVYtxLTdagh8mUo96coeRXfX7Uxorxr158"}'
   ```

   The answer is `202` with a `change_id`; follow it as in step 3.

## Keys held elsewhere

A key held by a company, a website or an environment is rotated the same way: read it with `GET /company/ssh`, `GET /websites/{website}/ssh` or `GET /environments/{environment}/ssh`, and name that owner when you add the new key. Company keys need the Company SSH Keys permissions.

Rotating an environment's host keys is a different thing: it replaces the keys the server proves itself with, not the keys people sign in with. The SSH keys reference has its endpoint.

## If it is refused

| Status | `reason`            | What to do                                                                                                                      |
| ------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `404`  | `feature_off`       | SSH keys are not on for your company yet                                                                                        |
| `409`  | `ssh_key_duplicate` | That key is already held here. Make a new key pair                                                                              |
| `422`  | `ssh_key_invalid`   | Send one public key in OpenSSH format, on one line                                                                              |
| `422`  | `ssh_key_weak`      | Use an ed25519 key, or RSA of at least 3072 bits                                                                                |
| `422`  | `ssh_cap_exceeded`  | The owner holds as many keys as it can. Remove one first                                                                        |
| `422`  | `invalid_arguments` | Correct the field named in `field`: a field is missing or wrong, or is not part of the request                                  |
| `422`  | `confirm_mismatch`  | `confirm_fingerprint` is not the key's fingerprint. Send it exactly as step 1 answered it                                       |
| `429`  | `ssh_throttled`     | Key changes are limited to 30 a minute for you and 120 a minute for your company. Wait for the seconds in `retry_after_seconds` |
