Keys
The SSH keys rookery logs in to hosts with.
| Operation | Kind | HTTP |
|---|---|---|
keys.list | call | GET /v1/keys |
keys.add | call | PUT /v1/keys/{name} |
keys.remove | call | DELETE /v1/keys/{name} |
keys.rotate | call | POST /v1/keys/{name}/rotate |
keys.list
The SSH keys of the server's key ring, by their public halves, with the hosts that log in with each and the key that replaces it while it rotates.
Needs the role admin.
Result
| Field | Type | Description |
|---|---|---|
keys | KeyInfo[] |
{
"id": 1,
"op": "keys.list"
}{
"id": 1,
"result": {
"keys": [
{
"fingerprint": "text",
"hosts": [
"text"
],
"id": "k3v9qz2m8w1x",
"name": "status",
"pending": {
"fingerprint": "text",
"hosts": [],
"id": "k3v9qz2m8w1x",
"name": "status",
"pending": {},
"public": "text"
},
"public": "text"
}
]
}
}keys.add
Add a key to the ring: a new ed25519 key without a body, or the OpenSSH private key in the body, which may have no passphrase. The answer has its public half only.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | The key's name: letters, digits, - and _, and not in the shape of an id |
Input
Bytes: {"base64": …} on the portal, the request body over HTTP.
Result
| Field | Type | Description |
|---|---|---|
fingerprint | string | Its SHA256 fingerprint, as ssh-keygen -l shows it. |
hosts (optional) | string[] | The server's hosts that log in with it. |
id (optional) | string | Its id; empty for the key that replaces another while it rotates. |
name | string | |
pending (optional) | KeyInfo | null | |
public | string | The public half, a line of authorized_keys. |
Errors
| Status | When |
|---|---|
| 400 | Not a name, not a private key, or a key with a passphrase |
| 409 | There is a key of that name |
{
"id": 1,
"op": "keys.add",
"args": {
"name": "status"
},
"data": {
"base64": "aGVsbG8K"
}
}{
"id": 1,
"result": {
"fingerprint": "text",
"hosts": [
"text"
],
"id": "k3v9qz2m8w1x",
"name": "status",
"pending": {
"fingerprint": "text",
"hosts": [
"text"
],
"id": "k3v9qz2m8w1x",
"name": "status",
"pending": {
"fingerprint": "text",
"hosts": [
"text"
],
"id": "k3v9qz2m8w1x",
"name": "status",
"pending": {
"fingerprint": "text",
"hosts": [],
"id": "k3v9qz2m8w1x",
"name": "status",
"pending": {},
"public": "text"
},
"public": "text"
},
"public": "text"
},
"public": "text"
}
}keys.remove
Remove a key from the ring. Refused for the key rookery, while a host logs in with the key, and while it rotates.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | The key, by its name or its id (bare or as key_ID) |
Result
| Field | Type | Description |
|---|---|---|
ok | boolean |
Errors
| Status | When |
|---|---|
| 404 | No such key |
| 409 | It is rookery's, in use or rotating |
{
"id": 1,
"op": "keys.remove",
"args": {
"name": "status"
}
}{
"id": 1,
"result": {
"ok": true
}
}keys.rotate
Replace a key on every host that takes it, as a job: a new key beside it, and on each host the new one added, a login with it checked, and the old one removed. A host that does not answer stays pending; running it again goes on from there. When none is pending the old key is deleted.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | The key, by its name or its id (bare or as key_ID) |
Result
| Field | Type | Description |
|---|---|---|
job (optional) | JobInfo | null | |
result (optional) | any | What an action that answers at once and changes nothing said. |
session (optional) | Session | null |
Errors
| Status | When |
|---|---|
| 404 | No such key |
| 409 | A rotation runs already |
{
"id": 1,
"op": "keys.rotate",
"args": {
"name": "status"
}
}{
"id": 1,
"result": {
"job": {
"id": "k3v9qz2m8w1x",
"started": "2026-11-12T09:30:00Z"
},
"result": null,
"session": {
"command": [
"uname -a"
],
"id": "k3v9qz2m8w1x",
"kind": "process",
"started": "2026-11-12T09:30:00Z",
"started_by": {
"level": "host",
"session": "k3v9qz2m8w1x",
"uid": 1001
},
"title": "uname -a",
"user": "agent"
}
}
}Types
The named types used on this page.
KeyInfo
A key of the ring, by its public half.
| Field | Type | Description |
|---|---|---|
fingerprint | string | Its SHA256 fingerprint, as ssh-keygen -l shows it. |
hosts (optional) | string[] | The server's hosts that log in with it. |
id (optional) | string | Its id; empty for the key that replaces another while it rotates. |
name | string | |
pending (optional) | KeyInfo | null | |
public | string | The public half, a line of authorized_keys. |
JobInfo
A job of rookery: one run of an action, with its output kept where it ran.
| Field | Type | Description |
|---|---|---|
action (optional) | string | The action it runs, such as apply, rollout or provision. |
arguments (optional) | string[] | What it was started with, as people may see it: the command of a resource's exec, or an action's arguments as NAME=VALUE. Never a secret argument, a password or standard input. |
ended (optional) | string | null | |
exit_code (optional) | integer | null | |
host (optional) | string | The hosts it is about, for a reader: a name, or several with commas. |
host_id (optional) | string | The ids of those hosts, as host lists them; a host in a file by its path. |
id | string | |
report (optional) | RolloutReport | null | |
started | string | |
stopped_by (optional) | string | null | Who stopped it before it ended by itself. |
subject (optional) | string | What it was done to, by id: host:ID, provisioner:ID, resource:ID or installation. Empty for a job recorded without one. |
subject_name (optional) | string | What it was done to, by name as it is called now: host:NAME, provisioner:NAME, resource:ID or installation; by id for one that is gone. |
Session
| Field | Type | Description |
|---|---|---|
action (optional) | string | null | The action it was started for, if any. |
cols (optional) | integer | null | |
command | string[] | |
ended (optional) | string | null | |
exit_code (optional) | integer | null | |
id | string | |
kind | SessionKind | |
last_output (optional) | string | null | |
lost (optional) | boolean | It ended with rookeryd or the host, not by itself. |
output_size (optional) | integer | |
rows (optional) | integer | null | |
started | string | |
started_by | From | Who did something, as rookeryd saw it. |
steps (optional) | Step[] | |
title | string | |
user | string | |
viewers (optional) | integer |
RolloutReport
The result of a roll-out, host by host in the order they were taken.
| Field | Type | Description |
|---|---|---|
hosts | RolloutHost[] | |
ok | boolean | Every host is done or current. |
SessionKind
From
Who did something, as rookeryd saw it.
| Field | Type | Description |
|---|---|---|
level | Level | |
session (optional) | string | null | |
uid | integer |
Step
| Field | Type | Description |
|---|---|---|
exit_code (optional) | integer | null | |
name | string | |
user | string |
RolloutHost
| Field | Type | Description |
|---|---|---|
changes (optional) | Change[] | What had changed, as it was before applying. |
error (optional) | string | What went wrong, for a failed host. |
name | string | |
rebooted (optional) | boolean | It was rebooted. |
state | RolloutState | How one host of a roll-out went. |
warnings (optional) | string[] | What did not go well without being a failure, such as an update step that ended badly. One stops the roll-out after this host. |
Level
Change
Something that changed since a host was applied: rookery itself or a plugin.
| Field | Type | Description |
|---|---|---|
from | string | The version the host was applied with. |
id | string | rookery, or a plugin's id. |
to | string | The version there is now; empty for a plugin that is gone, the same as from for one whose files changed. |
RolloutState
How one host of a roll-out went.
How one host of a roll-out went.