Skip to Content

Keys

The SSH keys rookery logs in to hosts with.

OperationKindHTTP
keys.listcallGET /v1/keys
keys.addcallPUT /v1/keys/{name}
keys.removecallDELETE /v1/keys/{name}
keys.rotatecallPOST /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

FieldTypeDescription
keysKeyInfo[]
Request
{
  "id": 1,
  "op": "keys.list"
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesThe 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

FieldTypeDescription
fingerprintstringIts SHA256 fingerprint, as ssh-keygen -l shows it.
hosts (optional)string[]The server's hosts that log in with it.
id (optional)stringIts id; empty for the key that replaces another while it rotates.
namestring
pending (optional)KeyInfo | null
publicstringThe public half, a line of authorized_keys.

Errors

StatusWhen
400Not a name, not a private key, or a key with a passphrase
409There is a key of that name
Request
{
  "id": 1,
  "op": "keys.add",
  "args": {
    "name": "status"
  },
  "data": {
    "base64": "aGVsbG8K"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesThe key, by its name or its id (bare or as key_ID)

Result

FieldTypeDescription
okboolean

Errors

StatusWhen
404No such key
409It is rookery's, in use or rotating
Request
{
  "id": 1,
  "op": "keys.remove",
  "args": {
    "name": "status"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesThe key, by its name or its id (bare or as key_ID)

Result

FieldTypeDescription
job (optional)JobInfo | null
result (optional)anyWhat an action that answers at once and changes nothing said.
session (optional)Session | null

Errors

StatusWhen
404No such key
409A rotation runs already
Request
{
  "id": 1,
  "op": "keys.rotate",
  "args": {
    "name": "status"
  }
}
Reply
{
  "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.

FieldTypeDescription
fingerprintstringIts SHA256 fingerprint, as ssh-keygen -l shows it.
hosts (optional)string[]The server's hosts that log in with it.
id (optional)stringIts id; empty for the key that replaces another while it rotates.
namestring
pending (optional)KeyInfo | null
publicstringThe public half, a line of authorized_keys.

JobInfo

A job of rookery: one run of an action, with its output kept where it ran.

FieldTypeDescription
action (optional)stringThe 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)stringThe hosts it is about, for a reader: a name, or several with commas.
host_id (optional)stringThe ids of those hosts, as host lists them; a host in a file by its path.
idstring
report (optional)RolloutReport | null
startedstring
stopped_by (optional)string | nullWho stopped it before it ended by itself.
subject (optional)stringWhat it was done to, by id: host:ID, provisioner:ID, resource:ID or installation. Empty for a job recorded without one.
subject_name (optional)stringWhat 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

FieldTypeDescription
action (optional)string | nullThe action it was started for, if any.
cols (optional)integer | null
commandstring[]
ended (optional)string | null
exit_code (optional)integer | null
idstring
kindSessionKind
last_output (optional)string | null
lost (optional)booleanIt ended with rookeryd or the host, not by itself.
output_size (optional)integer
rows (optional)integer | null
startedstring
started_byFromWho did something, as rookeryd saw it.
steps (optional)Step[]
titlestring
userstring
viewers (optional)integer

RolloutReport

The result of a roll-out, host by host in the order they were taken.

FieldTypeDescription
hostsRolloutHost[]
okbooleanEvery host is done or current.

SessionKind

SessionKind

From

Who did something, as rookeryd saw it.

FieldTypeDescription
levelLevel
session (optional)string | null
uidinteger

Step

FieldTypeDescription
exit_code (optional)integer | null
namestring
userstring

RolloutHost

FieldTypeDescription
changes (optional)Change[]What had changed, as it was before applying.
error (optional)stringWhat went wrong, for a failed host.
namestring
rebooted (optional)booleanIt was rebooted.
stateRolloutStateHow 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

Level

Change

Something that changed since a host was applied: rookery itself or a plugin.

FieldTypeDescription
fromstringThe version the host was applied with.
idstringrookery, or a plugin's id.
tostringThe 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.

RolloutState

How one host of a roll-out went.

On this page