SSH keys

For the whole flow, from key to shell, see Connect over SSH.

Register an SSH key: POST /me/ssh-keys, or the deprecated POST /organizations/{orgID}/ssh-keys
List your SSH keys: GET /me/ssh-keys
Revoke an SSH key: POST /me/ssh-keys/{keyID}/revoke
Login shell: GET /me and PUT /me/login-preferences

Register an SSH key

POST /me/ssh-keys
POST /organizations/{orgID}/ssh-keys

API: Business. Permission: none. No organization membership is needed. The organization route is a deprecated alias for personal registration. Its orgID does not scope the key or require membership of that organization, and registering through it grants no access to the organization. Use /me/ssh-keys. Adds a public key to your account. Every cluster in every organization where you hold clusters.ssh accepts it. Registering a key starts an access update on those clusters. GET /clusters/{clusterId}/ssh-access reports confirmed keys and their key-set generation. Compare that generation with this response to confirm the change reached a cluster; see Wait for access.

Your first active key adds you to the user list on clusters where you have SSH access, which restarts their compute nodes and ends running jobs. Further keys restart nothing. See Access changes restart nodes.

Parameters

Name	In	Type	Required	Description
`orgID`	path	string	deprecated route only	Organization ID. It has no effect on the key or your access.
`Idempotency-Key`	header	string	yes	1 to 200 characters. See Retrying writes.
`Audit-Reason`	header	string	yes	1 to 500 characters, stored with the change.

The OpenAPI document shows both headers as optional. They are required; a request without either returns 400.

Request body

Field	Type	Required	Description
`public_key`	string	yes	One Ed25519 public key in OpenSSH format, as in `~/.ssh/id_ed25519.pub`: `ssh-ed25519 AAAA… comment`. The comment is dropped.

Response

201 when the key is registered, 200 when the request replays an earlier one with the same Idempotency-Key.

Field	Type	Description
`ssh_key.id`	string	Key ID, `ssh_key_` + ULID.
`ssh_key.fingerprint`	string	SHA-256 fingerprint, `SHA256:…`, as printed by `ssh-keygen -lf`.
`ssh_key.key_type`	string	`ssh-ed25519`.
`ssh_key.public_material`	string	The key as stored, without its comment.
`ssh_key.user_id`	string	Your user ID.
`ssh_key.lifecycle_state`	string	`active`.
`ssh_key.created_at`	timestamp	When the key was registered.
`ssh_key.created_by_user_id`, `.created_command_id`, `.source_revision`		Audit details.
`ssh_key_set.generation`	integer	Version of your active key set. Increases with each new key or first revocation of an active key.
`ssh_key_set.user_id`, `.source_hash`, `.created_at`		Details of the key set.
`command_id`	string	ID of this registration.

Example

jq -n --arg key "$(cat ~/.ssh/id_ed25519.pub)" '{public_key: $key}' |
  andromeda call \
    --header "Idempotency-Key: $(uuidgen)" \
    --header 'Audit-Reason: Register SSH key' \
    --data @- \
    business POST /me/ssh-keys

{
  "ssh_key": {
    "id": "ssh_key_01J8Z3Q4R5S6T7V8W9X0Y1Z2A5",
    "user_id": "user_01J8Z3Q4R5S6T7V8W9X0Y1Z2A4",
    "key_type": "ssh-ed25519",
    "public_material": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGV4YW1wbGVrZXlmb3Jkb2N1bWVudGF0aW9ub25seQ",
    "fingerprint": "SHA256:Qm9vbGVhbiBhbGdlYnJhIGlzIHRoZSBrZXkgdG8gaXQ",
    "lifecycle_state": "active",
    "source_revision": 1,
    "created_by_user_id": "user_01J8Z3Q4R5S6T7V8W9X0Y1Z2A4",
    "created_command_id": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "created_at": "2026-09-30T18:00:00Z"
  },
  "ssh_key_set": {
    "user_id": "user_01J8Z3Q4R5S6T7V8W9X0Y1Z2A4",
    "generation": 1,
    "source_hash": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
    "created_at": "2026-09-30T18:00:00Z"
  },
  "command_id": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
}

Errors

This endpoint reports its own errors with error in place of message; see Errors.

Status	Code	When
400	`invalid_request`	A header is missing or too long, or `public_key` is not a single Ed25519 public key.
409	`invalid_state`	This key is already registered, to you or to anyone else.
409	`idempotency_mismatch`	The `Idempotency-Key` was used before with a different body.
503	`integration_unavailable`	Temporary. Retry with the same `Idempotency-Key`.

List your SSH keys

GET /me/ssh-keys

API: Business. Permission: none. No organization membership is needed. Returns every key you have registered, including revoked ones.

Response

Field	Type	Description
`keys[]`	array	Your keys, with the same fields as `ssh_key` in Register an SSH key.
`keys[].lifecycle_state`	string	`active`, or `revoked` for a key that no longer authenticates.
`keys[].revoked_at`	timestamp	When the revocation was accepted, for a revoked key.
`generation`	integer	Version of your key set; `0` before your first key.

Example

andromeda call business GET /me/ssh-keys | jq '.keys[] | {id, fingerprint, lifecycle_state}'

Revoke an SSH key

POST /me/ssh-keys/{keyID}/revoke

API: Business. Permission: none. No organization membership is needed; you can revoke only your own keys. Permanently revokes a key in every organization. A revoked key cannot be registered again. Each cluster where you can log in applies the change, and the gateway then closes sessions and forwarded connections that used the key. To confirm that a cluster has applied it, see Wait for access.

Revoking your last active key removes you from each cluster’s user list, which restarts its compute nodes and ends running jobs. Revoking a key while you keep another restarts nothing. See Access changes restart nodes.

Parameters

Name	In	Type	Required	Description
`keyID`	path	string	yes	The key’s `id`, `ssh_key_` + ULID.
`Idempotency-Key`	header	string	yes	See Retrying writes.
`Audit-Reason`	header	string	yes	Stored with the change.

Response

200, with ssh_key (now revoked), ssh_key_set (your new key set, with the next generation), and command_id. Repeating the request with the same Idempotency-Key returns the same result. Revoking a key that is already revoked, with a new Idempotency-Key, also returns 200: the key and your current key set, with generation unchanged, and no access update.

Errors

Status	When
400	A header is missing, or `keyID` is not an SSH key ID.
404	You have no key with this ID.
409	The `Idempotency-Key` was used before for a different key.

Example

andromeda call \
  --header "Idempotency-Key: $(uuidgen)" \
  --header 'Audit-Reason: Laptop lost' \
  business POST "/me/ssh-keys/$KEY_ID/revoke"

GET /me
PUT /me/login-preferences

API: Business. Permission: none. No organization membership is needed. Your login shell applies on every cluster where you can log in, in every organization. GET /me returns it as user.login_shell. PUT /me/login-preferences takes {"shell": "/bin/zsh"}, with Idempotency-Key and Audit-Reason headers, and returns 200 with shell and command_id. shell must be an absolute path; the default is /bin/bash. An empty or relative path, a path with a control character, or /usr/sbin/nologin returns 400; a malformed body can return 422. Sending your current shell again starts no access update. Your username, uid, gid, and home directory stay the same. New SSH sessions use the shell once the cluster has applied it. Open sessions are not closed and no nodes restart. If the shell is missing or not executable on the login node, the session falls back to /bin/bash. See Choose your login shell.

Example

andromeda call business GET /me | jq -r .user.login_shell

andromeda call \
  --header "Idempotency-Key: $(uuidgen)" \
  --header 'Audit-Reason: Prefer zsh' \
  --data '{"shell": "/bin/zsh"}' \
  business PUT /me/login-preferences

Overview

Business API

Platform API

Register an SSH key

Parameters

Request body

Response

Example

Errors

List your SSH keys

Response

Example

Revoke an SSH key

Parameters

Response

Errors

Example

Example

​Register an SSH key

​Parameters

​Request body

​Response

​Example

​Errors

​List your SSH keys

​Response

​Example

​Revoke an SSH key

​Parameters

​Response

​Errors

​Example

​Login shell

​Example

Register an SSH key

Parameters

Request body

Response

Example

Errors

List your SSH keys

Response

Example

Revoke an SSH key

Parameters

Response

Errors

Example

Login shell

Example