SSH keys¶

A project's SSH keys are the public keys its servers can be installed with. Choose them when you order a server or reinstall one, and you can log in as root with the matching private key.

Endpoints¶

Endpoint	What it does
GET `/projects/{slug}/ssh-keys/`	List SSH keys
POST `/projects/{slug}/ssh-keys/`	Add an SSH key
GET `/projects/{slug}/ssh-keys/{id}/`	Get an SSH key
PATCH `/projects/{slug}/ssh-keys/{id}/`	Rename an SSH key
DELETE `/projects/{slug}/ssh-keys/{id}/`	Delete an SSH key

The SSH key object¶

{
  "id": 3731,
  "name": "laptop",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEVixTZuGvU8D1V9aa9dGeyoy232lYd96rmgF27xLXF0",
  "fingerprint": "SHA256:OCKYOxqtDS41EAE0r/CqnopP+oYiNVHhN7k9Qm/R6lk",
  "created_at": "2026-03-18T00:00:00Z"
}

Field	Type	Description
`id`	integer	The key's id, which orders and reinstalls take.
`name`	string	The key's label.
`public_key`	string	The public key, as `<type> <key>`, without the comment it was added with.
`fingerprint`	string or null	The SHA256 fingerprint, as `ssh-keygen -lf` prints it. `null` for a key added before keys were checked that the API would refuse today, such as a DSA key.
`created_at`	string	The day the key was added. Only the day is recorded, so the time is midnight UTC.

Accepted keys¶

A public key is one line of a .pub file, in OpenSSH format, of up to 2048 characters. The API accepts these types:

Type	Notes
`ssh-ed25519`	Recommended.
`ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`
`ssh-rsa`	2048 bits or more.

Security keys (sk- types), certificates and DSA keys are refused. The comment after the key isn't kept: the name is the key's label. To make a key, run ssh-keygen -t ed25519 and add the contents of the .pub file it writes.

Keys¶

List SSH keys¶

GET /projects/{slug}/ssh-keys/

Any member · Read-only keys: yes · Returns 200 SshKey[]

The project's SSH keys.

Add an SSH key¶

POST /projects/{slug}/ssh-keys/

Any member · Read-only keys: no · Returns 201 SshKey

Add a public key to the project.

jq -n --arg key "$(cat ~/.ssh/id_ed25519.pub)" '{name: "laptop", public_key: $key}' |
  curl -X POST "https://console.hosthatch.com/api/v1/projects/acme/ssh-keys/" \
    -H "Authorization: Bearer $HOSTHATCH_API_KEY" \
    -H "Content-Type: application/json" \
    -d @-

Field	Type	Description
`name`	string	Required. Up to 255 characters: letters, digits, spaces, dots, `@`, underscores and hyphens.
`public_key`	string	Required. One public key, as above.

A key that is already in the project, whatever its comment, answers 409 key_exists, with the existing key's id in key_id. So a create whose answer you lost is safe to send again. While one request is adding a key, another adding the same key answers 409 conflict.

Get an SSH key¶

GET /projects/{slug}/ssh-keys/{id}/

Any member · Read-only keys: yes · Returns 200 SshKey

One of the project's keys.

Rename an SSH key¶

PATCH /projects/{slug}/ssh-keys/{id}/

Any member · Read-only keys: no · Returns 200 SshKey

Change the key's name. The public key itself can't change: add the new key and delete the old one. A body without name changes nothing.

{"name": "work laptop"}

Delete an SSH key¶

DELETE /projects/{slug}/ssh-keys/{id}/

Any member · Read-only keys: no · Returns 204

Delete the key from the project. Servers already installed with it still accept it: remove it from ~/.ssh/authorized_keys on them too.

Errors¶

Status	Code	When
400	`validation_error`	The name or the public key is invalid.
403	`read_only_key`	A change with a read-only key.
403	`billing_account_required`	The project's owner has no billing account.
403	`project_not_ready`	The project is still being set up.
404	`not_found`	No such key in the project.
409	`key_exists`	The key is already in the project.
409	`conflict`	Another request is adding the same key right now.
502	`upstream_error`	A system behind the API failed.