Skip to content

Add an SSH key to web hosting

POST /api/v2/shared-hosting/{accountId}/ssh-keys

Add an SSH public key to a web hosting account and authorize it for SSH and SFTP login in one call. Send the public key only, never the private key. A key with the same name or the same key already on the account returns 409 ssh_key_already_exists. The account must be active and on cPanel. The response has the key’s ID for later calls.

Authentication: An API key with the scopes write:hosting and console:services. About keys and scopes

Request

Path parameters

accountIdstringrequired
The web hosting account ID (acct_…).

Body

namestringrequired
A name for the key on the account, 1 to 255 characters.
publicKeystringrequired
The public key in OpenSSH format, on one line. Types: ssh-ed25519, ssh-rsa, ssh-dss, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, sk-ssh-ed25519@openssh.com and sk-ecdsa-sha2-nistp256@openssh.com.

Example

POST /api/v2/shared-hosting/{accountId}/ssh-keys
curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/ssh-keys" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "deploy-key",
"publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8g alex@example.com"
}'

Responses

201 The key was added and authorized.

Response 201
{
"id": "ssh_01hxa3b4c5d6e7f8g9h0j1k2m3",
"name": "deploy-key",
"fingerprint": "SHA256:mKqU+0K8OhKmA8bBQi9Rz0Q5l7/g160hIP+rJYSTNj4",
"imported": true,
"authorized": true
}
Response fields
idstring
The SSH key ID (ssh_…).
namestring
The key’s name on the account.
fingerprintstring
SHA-256 fingerprint of the public key.
importedboolean
True when the key was added to the account.
authorizedboolean
True when the key can log in.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400invalid_request: the body is invalid, the key is not a supported public key or the name or key has characters that are not allowed.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller.
409ssh_key_already_exists: a key with that name or public key is already on the account. account_not_eligible_cpanel: the account is not on cPanel.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.
502The key could not be added right now (upstream_failed). The key may be on the account without being authorized. List the keys before you retry.