API
A tenant's own automation speaks to Heinzel Pro over HTTP with JSON: a pipeline that asks the agent to check a deployment, a script that adds servers, a report that is fetched every morning.
Tokens
An administrator makes a token under API tokens. It is shown once. A token
- acts in the name of the person who made it, with no more than that person may do at the moment of the call; it ends when the person leaves the tenant or is disabled,
- is narrowed by its scopes:
read,sessions,servers, - can end after a number of days and can be revoked at any time,
- never approves a command. It sees what waits and it can deny; an approval is a person reading a command in the browser.
Every call carries the token in a header, and the tenant in the address:
curl -H "Authorization: Bearer hzp_…" https://host/api/v1/<tenant>/serversAn unknown tenant, a wrong token and an ended one all get 401 with the same
body. A call the token's scope does not cover, or that the token's person may
not make, gets 403; one that cannot be carried out as things stand (a session
that is busy, a command that is no longer waiting) gets 409. Calls are counted
per address before the token is looked at (120 a minute by default).
Calls
| Call | Scope | What it does |
|---|---|---|
GET /servers | read | The servers, each with its logins (logins); ssh_user and sudo are the first one's. |
POST /servers | servers | Adds one: hostname, optional ssh_user and sudo (its first login), port, description, tags and ceiling (-, r, rw, rwx; the old mode with managed, read_only, blocked, and the old owner_mode, still set it). Returns the public key to install on it. |
GET /sessions | read | The sessions the token's person may see. |
POST /sessions | sessions | Starts one: server (host name) and task. Returns its id and address. |
GET /sessions/:id | read | State, the agent's last answer, its summary, the commands. |
POST /sessions/:id/messages | sessions | Writes text into a session. |
GET /sessions/:id/record | read | The change record as Markdown. Ask with Accept: application/json or none; the answer is text/markdown. |
GET /approvals | read | The commands that wait for a person, for a token whose person may approve. |
POST /approvals/:id/deny | sessions | Denies one, with an optional note. |
GET /findings | read | The open findings. |
GET /schedules | read | The schedules. |
POST /schedules/:id/run | sessions | Runs one now. |
A session started through the API is an ordinary session: its commands wait for approval as the policy says, and its page in the browser is where they are approved.
The heinzel command
cli/heinzel in the repository is a shell script on top of these calls. It
needs curl, and jq for readable listings.
export HEINZEL_URL=https://host/api/v1/<tenant>
export HEINZEL_TOKEN=hzp_…
heinzel run web1.example.com "Check why nginx returns 502"
heinzel show <session>
heinzel approvalsThe token is handed to curl in a file only you can read, not on the command
line.