Admin API

The administrative API is the only way anything on Nixt Server is administered. versealx-server admin is a client of it; so is any script you write. Every change goes through one path that checks the caller’s role, makes the change and writes the audit line in the same transaction, so a change cannot happen without its record.

Reaching the API

Both answer the same API. Paths begin with /api/v1.

The operator’s console

The console’s System pages — the cluster, disaster recovery and links — are the operator’s, and the operator is reached only from inside the server. On the server, as the service user, open the console on this machine:

sudo -u versealx versealx-server console serve --from /srv/versealx-console

--from is where a console release is installed (versealx-server console install). The command prints an address like http://127.0.0.1:43127/#operator=…. Open it in a browser on the server, or from your own machine through an SSH tunnel to that port:

ssh -L 43127:127.0.0.1:43127 admin@mail.example.com

In a cloud, your provider’s session manager port forwarding does the same. The console listens on the loopback address only and passes its calls to the local socket. The key in the address works until you stop the command with Ctrl-C; without it, nothing is answered. --port picks the port.

With versealx-server admin

sudo -u versealx versealx-server admin get tenants --config /etc/versealx-server/versealx-server.toml

Values in a body are typed: true and false become booleans, null becomes null, a value made only of digits becomes a number, and a value starting with [ or { that parses as JSON is sent as that JSON. Everything else is a string. Quote pairs that contain spaces or shell characters.

The command prints the answer’s JSON, indented, and exits 0 for a success, 1 when the API answered with an error (4xx or 5xx), and 2 when the call could not be made at all.

With curl over the socket

sudo -u versealx curl --unix-socket /var/lib/versealx-server/admin.sock http://localhost/api/v1/tenants

Over HTTPS

[listeners.admin]
bind = "0.0.0.0:443"

With this table, the API answers on the shared HTTPS listener beside JMAP. Requests need an Authorization: Bearer <token> header carrying a token issued by this server for the versealx-admin audience; the token’s scopes name the caller’s role. See Roles and the audit log.

For a script or an identity provider — anything that cannot sit at the terminal and cannot open the socket — mint a provisioning token. It goes in the same Authorization: Bearer header, and the API treats it exactly as it treats any other credential carrying those scopes.

Requests and answers

• Request bodies are JSON, at most 256 KiB.
• Successful answers are JSON: 200 with the thing, 201 with a newly created thing, or 204 with no body.
• Lists are wrapped as {"items": [...]}.
• Times are Unix milliseconds unless a field says otherwise.
• Reads are not audited unless refused; every change, successful, failed or refused, is.

The OpenAPI document

vsx admin get openapi.json

GET /api/v1/openapi.json returns an OpenAPI 3.1 description of every endpoint, including the Settings schema that lists every runtime setting. It needs no credentials. Endpoints only the operator may call are marked x-operator-only.

Endpoints

Provisioning tokens

The credential a machine authenticates with. See Provisioning with SCIM.

Tenants

Domains

Accounts

Domains and accounts shows each of these with examples and answers.

Settings

Runtime settings lists every key.

Queue and trace

tenant is the caller’s own tenant unless an operator names one. For /queue, an operator who names none sees every tenant’s messages; for /trace, an operator must name one. See Message trace for the fields.

Reports

See Email authentication for the fields.

Audit log

See Roles and the audit log.

Documentation

Errors

Every error is an RFC 9457 problem document, with the content type application/problem+json:

{
  "detail": "example.org is already taken",
  "status": 409,
  "title": "Conflict",
  "type": "about:blank"
}

detail says what went wrong in words you can act on. It never says more about the server than the caller is entitled to know: a queue id or trace id that belongs to someone else gets the same 404 as one that does not exist.

When the problem is at one place in what you sent, errors says where, as RFC 9457 §3 writes it: each entry repeats the detail and adds a pointer into the body, such as #/until, or #/delegates/1 for the second delegate in a list. A form can show the words beside the field they are about. A problem about the request as a whole has no errors.

{
  "detail": "`until` is later than now: a hold that has already ended holds nothing",
  "errors": [
    {
      "detail": "`until` is later than now: a hold that has already ended holds nothing",
      "pointer": "#/until"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "about:blank"
}

Requests that change something and are refused or fail are recorded in the audit log with the reason.