## PATCH /api/v2/vps/{id}/ssh-access

**Change the SSH keys that can log in to a VPS**

Removes chosen key lines from `~/.ssh/authorized_keys` on the running VPS and adds saved account keys to it. Other lines stay as they are, options included. Read `GET /api/v2/vps/{id}/ssh-access` first. Send its `revision` and the `entries[].id` values to remove. If the file changed since that read, nothing is written and the call returns 409 `ssh_access_changed`. The file is read back after the write. The response is the new list with `lastOperation`. Removing every key needs `confirmRemoveAll: true`. With no keys left, the login user cannot log in with an SSH key.

### Related Endpoints

- `GET /api/v2/vps/{id}/ssh-access`: List the SSH keys that can log in to a VPS
- `GET /api/v2/vps/{id}`: Get a VPS
- `GET /api/v2/vps/{id}/iso`: List ISO images and CD/DVD drives

### Headers

- `Authorization`: Bearer $HOSTUP_API_KEY
- Scope: `write:vm`
- `Content-Type`: application/json

### Parameters

- `id` (path, string, required): The VPS ID (`vps_…`). Example: `vps_01hxa3b4c5d6e7f8g9h0j1k2m3`

### Request Body

- `revision` (string, required): `revision` from the latest GET. Example: `9b74c9897bac770ffc029102a200c5de6e2c7e1c4f2a3b8d0e5f6a7b8c9d0e1f`
- `removeEntryIds` (array<string>, required): `entries[].id` values to remove. Send `[]` to remove nothing. Example: `["ak_3f9a1c7e5b2d8a4c6e0f1b3d5a"]`
- `addSshKeyIds` (array<string>, required): Saved SSH key IDs (`ssh_…`) to add. A key that is already in the file is not added twice. Send `[]` to add nothing. Example: `["ssh_01hxa3b4c5d6e7f8g9h0j1k2m3"]`
- `confirmRemoveAll` (boolean, optional): Set to true when the change leaves no keys in the file. Default false. Example: `false`

### Request Examples

#### Remove a key added inside the VPS and add a saved key

```bash
curl -X PATCH "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/ssh-access" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "revision": "9b74c9897bac770ffc029102a200c5de6e2c7e1c4f2a3b8d0e5f6a7b8c9d0e1f",
    "removeEntryIds": [
      "ak_3f9a1c7e5b2d8a4c6e0f1b3d5a"
    ],
    "addSshKeyIds": [
      "ssh_01hxa3b4c5d6e7f8g9h0j1k2m3"
    ]
  }'
```

```json
{
  "revision": "9b74c9897bac770ffc029102a200c5de6e2c7e1c4f2a3b8d0e5f6a7b8c9d0e1f",
  "removeEntryIds": [
    "ak_3f9a1c7e5b2d8a4c6e0f1b3d5a"
  ],
  "addSshKeyIds": [
    "ssh_01hxa3b4c5d6e7f8g9h0j1k2m3"
  ]
}
```

### Response Schema

- `available` (boolean, required): Always true after a change. Example: `true`
  Allowed values: true
- `unavailableReason` (null, required): Always null after a change. Example: `null`
- `unavailableMessage` (null, required): Always null after a change. Example: `null`
- `loginUser` (string, required): The user whose `~/.ssh/authorized_keys` was read. The VPS's default login user, usually `root`. Example: `root`
- `checkedAt` (string, required): When the file was read. Example: `2026-08-13T10:00:00.000Z`
- `revision` (string, required): The new version of the file. Send it with the next PATCH. Example: `2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae`
- `entries` (array<object>, required): Every public key line in the file, including keys added inside the VPS.
- `entries[].id` (string, required): ID of this line in the file. It changes when the line or its position changes. Use it in `removeEntryIds`. Example: `ak_3f9a1c7e5b2d8a4c6e0f1b3d5a`
- `entries[].keyType` (string, required): Key algorithm. Example: `ssh-ed25519`
- `entries[].fingerprint` (string, required): SHA256 fingerprint of the public key. Example: `SHA256:exampleFingerprint`
- `entries[].comment` (string, required, nullable): Comment at the end of the key line. Example: `alex@laptop`
- `entries[].restricted` (boolean, required): True when the line has OpenSSH options that limit the key. Example: `false`
- `entries[].restrictions` (array<string>, required): The options on the line. `forced_command` is `command=`, `source_restricted` is `from=`, `expires` is `expiry-time=`, `restricted` is `restrict`. `custom_options` covers any other option. The values of the options are not returned. Example: `[]`
- `entries[].savedKeyId` (string, required, nullable): The saved SSH key on your account with the same public key. Null when the key is not saved on the account. Example: `ssh_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `entries[].savedKeyName` (string, required, nullable): Name of that saved key. Example: `Laptop`
- `savedKeys` (array<object>, required): The SSH keys saved on your account and whether each one is in the file.
- `savedKeys[].id` (string, required): Saved SSH key ID. Use it in `addSshKeyIds`. Example: `ssh_01hxa3b4c5d6e7f8g9h0j1k2m3`
- `savedKeys[].name` (string, required): Name of the saved key. Example: `Laptop`
- `savedKeys[].fingerprint` (string, required, nullable): SHA256 fingerprint of the key. Example: `SHA256:exampleFingerprint`
- `savedKeys[].active` (boolean, required): True when the key is in the file now. Example: `true`
- `savedKeys[].activeEntryIds` (array<string>, required): The `entries[].id` values that hold this key. Example: `["ak_3f9a1c7e5b2d8a4c6e0f1b3d5a"]`
- `lastOperation` (object, required): What this change did.
- `lastOperation.added` (integer, required): Number of saved key IDs sent in `addSshKeyIds`. Example: `1`
- `lastOperation.removed` (integer, required): Number of lines removed. Example: `1`
- `lastOperation.verified` (boolean, required): Always true. The file was read back and matches the change. Example: `true`
  Allowed values: true
- `lastOperation.metadataSynced` (boolean, required): True when the VPS's cloud-init key list was also set to the saved keys now in the file. A rebuild then installs the same keys. Example: `true`

### Responses

#### 200 - The change is written and read back. Same shape as the GET, plus `lastOperation`.
```json
{
  "available": true,
  "unavailableReason": null,
  "unavailableMessage": null,
  "loginUser": "root",
  "checkedAt": "2026-08-13T10:01:00.000Z",
  "revision": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
  "entries": [
    {
      "id": "ak_7c9e1f3a5b2d8a4c6e0f1b3d5a",
      "keyType": "ssh-ed25519",
      "fingerprint": "SHA256:exampleFingerprint",
      "comment": "alex@laptop",
      "restricted": false,
      "restrictions": [],
      "savedKeyId": "ssh_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "savedKeyName": "Laptop"
    }
  ],
  "savedKeys": [
    {
      "id": "ssh_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "name": "Laptop",
      "fingerprint": "SHA256:exampleFingerprint",
      "active": true,
      "activeEntryIds": [
        "ak_7c9e1f3a5b2d8a4c6e0f1b3d5a"
      ]
    }
  ],
  "lastOperation": {
    "added": 1,
    "removed": 1,
    "verified": true,
    "metadataSynced": true
  }
}
```

#### 400 - Invalid body. `code` is `invalid_request`. It is `confirmation_required` when the change would leave no keys and `confirmRemoveAll` is not true.
```json
{
  "type": "https://developer.hostup.se/errors/confirmation_required",
  "title": "Confirmation required",
  "status": 400,
  "detail": "Confirm that every SSH access entry should be removed from this server.",
  "code": "confirmation_required",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/ssh-access",
  "errors": [
    {
      "pointer": "/confirmRemoveAll",
      "detail": "Confirm that every SSH access entry should be removed from this server.",
      "code": "confirmation_required"
    }
  ]
}
```

#### 401 - Unauthorized. Authentication is required.
```json
{
  "type": "https://developer.hostup.se/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required.",
  "code": "unauthorized",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 403 - Forbidden. The caller lacks a required scope or does not own the resource.
```json
{
  "type": "https://developer.hostup.se/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The caller lacks a required scope or does not own the resource.",
  "code": "forbidden",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 404 - Not found. The resource does not exist or is not owned by the caller; `code` is `vps_not_found`.
```json
{
  "type": "https://developer.hostup.se/errors/vps_not_found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "code": "vps_not_found",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 409 - The change was not made or could not be read back. `code` is `ssh_access_unavailable` (the file cannot be read, for example the VPS is stopped), `ssh_access_changed` (the file changed since your GET: read it again), `ssh_access_update_failed` (the write failed and the old file is kept) or `ssh_access_verification_failed` (the write ran but could not be read back: check access through the console).
```json
{
  "type": "https://developer.hostup.se/errors/ssh_access_changed",
  "title": "SSH access changed",
  "status": 409,
  "detail": "The server's SSH access list changed after it was loaded. Review the current entries and try again.",
  "code": "ssh_access_changed",
  "instance": "/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/ssh-access"
}
```

#### 429 - Rate limited. Retry after the limit resets. 429 responses include `Retry-After` seconds plus `X-RateLimit-*` headers.
```json
{
  "type": "https://developer.hostup.se/errors/rate_limit_exceeded",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please try again later.",
  "code": "rate_limit_exceeded",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 500 - Internal error. Retry later or contact support if the issue persists.
```json
{
  "type": "https://developer.hostup.se/errors/internal_error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred. Retry later or contact support if the issue persists.",
  "code": "internal_error",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```
