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
readandwritescopes. - 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 when your company requires it.
- No step waits for a maintenance window.
Read your keys
Note your
user_id, and theidandfingerprintof the key to replace.curl https://manage.corefinity.com/api/user/ssh \ -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json"Add the new key
Send the public key with a name to recognise it by. For a key of your own,
ownerisuserwith youruser_id.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
201with the key and achange_idto follow. Notekey.idandchange_id.Follow the change
Adding a key answers a change, not an operation. Read it every few seconds until its
stateisappliedorfailed;failedlists the environments that did not take it.curl https://manage.corefinity.com/api/ssh/changes/5184 \ -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json"Check the new key
Read your keys again. The new key's
delivery.stateisapplied, andreachlists each environment with thecommandthat signs you in.Sign in with the new key before you remove the old one.
curl https://manage.corefinity.com/api/user/ssh \ -H "Authorization: Bearer $COREFINITY_TOKEN" -H "Accept: application/json"Remove the old key
Send the old key's fingerprint, exactly as step 1 answered it, as
confirm_fingerprint.This deletes the old key from your keys: it stops working on every environment it reached through you.
remaining_sourcesin the answer lists the places the same key is still held, such as a company key.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
202with achange_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 |