---
title: "Replace CVM SSH keys"
method: PUT
path: "/api/v1/cvms/{cvm_id}/ssh-keys"
tags: ["CVMs"]
---

# Replace CVM SSH keys

`PUT /api/v1/cvms/{cvm_id}/ssh-keys`

## Request

- Base URL: `https://cloud-api.phala.com`
- URL: `https://cloud-api.phala.com/api/v1/cvms/{cvm_id}/ssh-keys`
- Auth: none declared
- TypeScript: <https://skmtc.dev/phala/apis/phala-cloud-api/docs/api/v1/cvms/:cvm_id/ssh-keys/put.ts> (a function with typed inputs; its response is checked against the schema)

Replaces the set of SSH keys this CVM authorizes. Optional usernames are resolved to that member's keys and unioned into the set. Keys take effect at the next power-on, or immediately when apply_now restarts the CVM.

## Path parameters

- `cvm_id` string, required

## Request body

- UpdateCvmSshKeysRequest: Replace the CVM's authorized key set.
  - `ssh_key_ids` string[], required: SSH key hashids to authorize. Must belong to a workspace member. Keys currently authorized but missing here are withdrawn.
  - `usernames` string[]: Workspace member usernames whose keys are unioned into the set. Each name must be a current member with at least one SSH key.
  - `apply_now` boolean: Restart the CVM so the change takes effect immediately. When false the change applies at the next power-on.

## Response `200`

Updated authorized keys

- CvmSshKeysResponse: The keys a CVM is configured to authorize. This is the desired set. It reaches the guest at the next power-on; read ``GET /cvms/{cvm_id}/user_config`` for what the running VM actually has.
  - `keys` CvmSshKeyEntry[]
    - `id` string, hashid, required: SSH key hashid
    - `owner_user_id` string, hashid, required: User who owns the key
    - `owner_username` string, required: Username of the key owner
    - `added_by_user_id` string, hashid, required: User who authorized it on this CVM
    - `name` string, required: Human-readable key name
    - `public_key` string, required: OpenSSH format public key
    - `fingerprint` string, required: SHA256 fingerprint
    - `key_type` string, required: Algorithm (ssh-ed25519, ssh-rsa, ...)
  - `restart_required` boolean, required: True when the stored set has not been applied to the running VM yet

## Other responses

- `400`: A named member holds no SSH keys
- `401`: Not authenticated
- `404`: CVM, SSH key, or username not found in this workspace
- `409`: Another operation is already in progress for this CVM
- `422`: Validation Error

## Changes

- **2026-11-07** `c71a8dc90391`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/phala/apis/phala-cloud-api/changes/api/v1/cvms/:cvm_id/ssh-keys/put.md)

---

[API](https://skmtc.dev/phala/apis/phala-cloud-api.md) - [All operations](https://skmtc.dev/phala/apis/phala-cloud-api/llms.txt) - [OpenAPI document](https://skmtc.dev/phala/apis/phala-cloud-api/revisions/c71a8dc90391?raw)