Goal
Safely create, verify, rotate, and delete the SSH credentials used to connect to target deployment servers.
When to use this task
- Configuring SSH access for a server for the first time.
- Rotating credentials periodically, or when you suspect a private key may have leaked.
- Cleaning up a saved credential you no longer need after decommissioning a server.
Prerequisites
- You’ve completed Register And Connect A Server.
- A new SSH private key is ready (rotation scenario).
Inputs and defaults
A credential can take one of three forms:
| Form | Good for | Description |
|---|---|---|
| Local key path | CLI local execution only | Only the CLI can read the local file system |
| Private key content | One-time input | Treated as a sensitive secret — never echoed after submission |
| Saved credential | Web / API / reuse scenarios | An Appaloft-stored, reusable credential reference |
Credentials are a security boundary: Web, CLI, API, logs, and diagnostic summaries never show a plaintext private key, passphrase, or token.
CLI steps
# Provide a local key path directly when registering a server
appaloft server register --host 203.0.113.10 --user deploy --ssh-key ~/.ssh/id_ed25519
# Rotate a saved, reusable credential (in-place rotation, keeps the credential id and existing server references)
appaloft server credential-rotate <credentialId> \
--private-key-file ~/.ssh/appaloft-new \
--confirm <credentialId> \
--acknowledge-server-usage
# Delete a saved credential that's no longer referenced by any server
appaloft server credential-delete <credentialId> --confirm <credentialId>--acknowledge-server-usage can only be omitted when the credential is currently used by 0 servers; once any server is using it, you must explicitly confirm you understand those servers will switch to the rotated key material.
HTTP/API steps
POST /api/credentials/ssh/{credentialId}/rotate
DELETE /api/credentials/ssh/{credentialId}Expected output and status
Successful rotation only means Appaloft has saved new key material — it does not mean the new key can already reach the server. A delete request is rejected with credential_in_use if the target credential is still referenced by at least one server.
Verification
After rotating, make sure to rerun the connectivity test on every server that references the credential:
appaloft server test srv_primaryRollback / recovery
- If you’d rather create a brand-new credential id instead of rotating in place: add the new credential → switch the server(s) to it → run the connectivity test to confirm → then delete the old credential.
- If the connectivity test fails after rotation, first confirm the new private key’s matching public key has been added to the server’s
authorized_keys, then retry the connectivity test — the old credential is not automatically deleted until rotation is complete.