CorefinityCorefinityDocs
Open the Control PanelControl Panel
Recipes · 6 of 8

Rotate an SSH key

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

On this page

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.
  • 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.
  1. Read your keys

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

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

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

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

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

    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.

    Terminal
    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

StatusreasonWhat to do
404feature_offSSH keys are not on for your company yet
409ssh_key_duplicateThat key is already held here. Make a new key pair
422ssh_key_invalidSend one public key in OpenSSH format, on one line
422ssh_key_weakUse an ed25519 key, or RSA of at least 3072 bits
422ssh_cap_exceededThe owner holds as many keys as it can. Remove one first
422invalid_argumentsCorrect the field named in field: a field is missing or wrong, or is not part of the request
422confirm_mismatchconfirm_fingerprint is not the key's fingerprint. Send it exactly as step 1 answered it
429ssh_throttledKey changes are limited to 30 a minute for you and 120 a minute for your company. Wait for the seconds in retry_after_seconds
Was this helpful?
Open in ClaudeOpen in ChatGPT