A hosted deployment has an operator: someone who looks after many customers' orgs and is not one
of them. The operator API is what a separate console talks to for that. It is generic (orgs, jobs
as numbers, an audit log) and nothing in it is specific to one business. It is off unless
PRINTAPI_OPERATOR_TOKEN is set: with the token unset, every path under /operator/ answers
404, as if the API did not exist.
This page covers the gate, hosted mode, the audit log, the read endpoints (overview, orgs and their jobs), the write endpoints (change, lock, delete and create an org, send a reset mail, revoke a key), support access and live settings.
Two settings, both required together:
| Variable | Meaning |
|---|---|
PRINTAPI_OPERATOR_TOKEN |
The credential of the operator API. At least 32 characters, not starting with sess_, different from PRINTAPI_TOKEN. Anything else stops the server at startup |
PRINTAPI_OPERATOR_FROM |
The addresses it is accepted from: IPs or CIDRs, same syntax as PRINTAPI_TRUSTED_PROXIES (server). Required when the token is set |
A request passes the gate when it carries the token as Authorization: Bearer and its socket
peer is in PRINTAPI_OPERATOR_FROM. The peer is the address the TCP connection came from. A
trusted proxy's X-Forwarded-For is never read for this, so a caller who can reach the proxy cannot
name the console's address. From any other peer the token is an unknown credential and the answer
is 401.
- The root token (
PRINTAPI_TOKEN) is not accepted on/operator/:401. Otherwise the address rule would bind only the operator token, and root could read the same data from anywhere. - The operator token is no credential anywhere else. On every other route it is dropped before
a session, API key, HTTP Basic (PrintNode), CloudPRNT or agent key is looked up, so it answers as
if no credential had been sent; an agent cannot enroll with it, even with
PRINTAPI_OPEN_ENROLLMENT=1. - Every
/operator/response carriesCache-Control: no-store, the unauthorized and404ones too. - With
LOG_REQUESTS, the access log writes/operator/paths without their query string (a search can name a customer). - There is one operator identity. Every audit row says
actor = operator.
Keep the console off the public host. In a Caddy setup, answer 404 for /operator/* on the
public site and let the console reach printpapi over the internal network:
printpapi.example.com {
@operator path /operator/*
respond @operator 404
reverse_proxy printpapi:3460
}Setting the operator token turns on hosted mode, because strangers' jobs run on this server:
PRINTAPI_PRIVATE_URLSunset meansdeny(payload URLs, callbacks and event URLs may only reach public addresses), whateverPRINTAPI_SIGNUPsays.PRINTAPI_FETCHES_PER_ORGunset means4.
Both are fixed at startup. Set either explicitly and your value wins, for example
PRINTAPI_PRIVATE_URLS=allow. Setting the token never changes what these mean on a later upgrade.
Table operator_audit: id, at, actor, action, org_id, org_created_at, target,
reason, detail. org_created_at tells an org apart from an older one that had the same id.
- It holds ids, numbers and setting values, never an e-mail address, a name or a job title, so deleting a customer does not leave one behind.
- It is kept for ever. No API changes or deletes a row, and deleting an org does not remove its
rows. It does not follow
PRINTAPI_JOB_RETENTION_DAYS. Trim it by hand if it ever grows past about 100 000 rows. - It records
/operator/actions only. Root's own routes (for exampleGET /jobs, which lists titles across orgs) are not audited. - It lives in a table of its own: the Python server of v2.x ignores it, and a rollback keeps it.
Newest first. Query: org, action (exact), before_id, limit (default 50, at most 200).
{
"entries": [
{"id": 12, "at": 1760000000.5, "actor": "operator", "action": "org.update",
"org_id": 3, "org_created_at": 1750000000.0, "target": null,
"reason": "quota raised after support request", "detail": {"job_quota": 500}}
],
"next_before_id": 9
}next_before_id is the id to pass as before_id for the next page, null on the last one.
A parameter that is not an integer answers 400.
GET /operator/overview answers counts and server numbers. It never contains a job payload, title,
callback, idempotency key, key secret or password hash.
{
"orgs": 41, "orgs_active_7d": 17, "signups_7d": 3,
"jobs_this_month": 5120, "failed_jobs_30d": 12,
"jobs_today": {"queued": 0, "claimed": 1, "done": 188, "failed": 2, "cancelled": 0},
"server": {"version": "3.6.0", "uptime_s": 86400},
"db": {"size_bytes": 12582912, "wal_bytes": 0},
"retention": {"last_pass_at": 1760000000.0, "abandoned": 0, "scrubbed": 14, "deleted": 0},
"features": ["support", "settings"]
}orgs counts every org including the default one; signups_7d does not count the default org.
jobs_today is the current UTC day. retention is null fields until the first pass has run.
features lists the optional sections this server offers, so a console can hide the ones an older
server lacks. The answer is cached for 10 seconds.
Metadata only. Never in any answer: a job's payload, title, callback URL or idempotency key, an
API or agent key (nor its hash), a password hash, or an org's Shopify secret. All three are GET
only, and an org that does not exist (or an id that is not a number) answers 404.
Query: status (locked, new, idle or active), q, limit (default 50, at most 200),
after. Ordered by org id, oldest first.
qmatches a part of the org name or of a user's e-mail address.%and_mean themselves. Case is ignored for ASCII letters only (SQLiteLIKE).statusis derived, in this order:locked(the org has a lock),new(created less than 7 days ago),idle(no job in the last 14 days, or never one), otherwiseactive.afteris thenext_afterof the previous page;next_afterisnullon the last page. A parameter that is not an integer, or an unknownstatus, answers400.
{
"orgs": [
{"id": 3, "name": "Acme", "created_at": 1750000000.0, "plan": "pro", "job_quota": 500,
"jobs_this_month": 212, "queued_jobs": 0, "failed_today": 1, "last_job_at": 1760000000.0,
"agents_online": 1, "agents_total": 2, "newest_agent_seen_at": 1760000100.0, "printers": 3,
"locked": false, "first_user_email": "boss@acme.example",
"terms_version": "2026-11", "terms_accepted_at": 1750000000.0, "status": "active"}
],
"next_after": null
}job_quota is null for unlimited. jobs_this_month is the current UTC month, failed_today
counts jobs created today (UTC) that failed, queued_jobs all jobs still queued. An agent is
online when it polled in the last minute. The statement
runs on indexes only (one lookup per org), so a page costs its size, not the size of jobs. A
status filter computes the numbers of every org it passes over.
The row above plus:
| Field | Content |
|---|---|
usage_by_day |
every UTC day of the current month up to today: {date, jobs, failed}. Earlier months are not offered: with job retention they would be incomplete |
users |
id, email, created_at |
agents |
id, name, last_seen_at, online |
printers |
id, name, can_pdf, state, agent_id |
keys |
id, label, active, created_at: the key itself is never shown |
terms |
the acceptance history, oldest first: version, accepted_at |
lock |
null, or {reason, locked_at} while the org is locked |
support |
null, or the active support grant {id, reason, granted_at, expires_at, reads} (see Support access) |
Query: limit (default 50, at most 200), before_id. Newest first by id. Each job has id,
created_at, claimed_at, finished_at, type, mode, state, printer_id, printer_name,
copies and error. next_before_id is the id to pass as before_id for the next page, null
on the last one.
?titles=1 adds each job's title while the org has an active support grant, and writes an audit
row (see Support access). Without titles=1 a job never carries a title.
The reads add indexes (jobs(org_id), jobs(org_id, state) and three small ones) to an existing
database at startup. They are additive and the Python server of v2.x ignores them.
Every write is one store function and one transaction with its audit row: the change and the
row are committed together or not at all. If the audit row cannot be written, the change is rolled
back and the answer is 500. A mail and the WAL truncate that belong to an action run after the
commit. Bodies are JSON; the optional reason is a string of at most 500 characters and lands in
the audit log, so keep customer data out of it. An org or id that does not exist answers 404; a
body that is not a JSON object, or a field that fails validation, answers 400 and changes nothing.
Every write on an existing org names its generation. Org and user ids are reused by SQLite after
the newest row is deleted, so an id alone does not say which customer a page showed. Each write
(PUT, lock, unlock, DELETE of an org, the user reset and the key revoke) carries
org_created_at, the created_at the read endpoints returned for that org, and the server compares
it with the org's created_at inside the transaction. A different or missing value answers 409
the org changed, reload; nothing is changed, no audit row is written and no mail goes out.
POST /operator/orgs creates the org and takes none.
| Call | Audit action |
|---|---|
PUT /operator/orgs/{id} |
org.update |
POST /operator/orgs/{id}/lock, .../unlock |
org.lock, org.unlock |
DELETE /operator/orgs/{id} |
org.delete |
POST /operator/orgs |
org.create |
POST /operator/users/{id}/reset |
user.reset (user.reset_mail_failed when the mail did not go out) |
DELETE /operator/keys/{id} |
key.revoke |
The audit rows hold ids and numbers: org.update says which fields changed (name: true, never the
name), org.lock how many queued jobs it cancelled, org.create the quota the org started with.
No e-mail address, org name or title is ever written.
{name?, job_quota?, plan?, reason?}, at least one of the three fields. Everything is validated
first and applied in one transaction. name is a non-empty string of at most 200 characters;
job_quota a non-negative integer or null (unlimited); plan an id of the plan catalogue
(billing), which also sets the quota the plan grants. An explicit job_quota in the
same body wins over the plan's. Answer: {"ok": true}.
POST /operator/orgs/{id}/lock with {reason} of at least 8 characters inserts a row into the
table org_locks (org_id, org_created_at, reason, locked_at) and cancels the org's queued
jobs (error: "org locked"). A job an agent had already claimed is not interrupted; if that agent
goes quiet, the reaper cancels the job (org locked) instead of putting it back in the queue.
Answer: {"ok": true, "cancelled_jobs": 3}; 409 if the org is already locked.
A lock is a pure flag: quota and plan stay as they are, so billing and quota writes need no
change. While it is set, every way a job gets in answers 403 org locked: POST /jobs,
POST /orders, the Shopify webhook and the PrintNode-compatible POST /printjobs. The check sits
next to the quota check in the enqueue path and again before any payload is downloaded, so a locked
org causes no outbound request, and an idempotent resubmit does not get an old job back either.
Logins, the dashboard and agents keep working, so the customer can see what is going on.
A lock row belongs to one org generation: it counts only while its org_created_at equals the
org's created_at. A row left by an earlier org of the same id locks nothing and shows nowhere.
Locks are enforced only while PRINTAPI_OPERATOR_TOKEN is set. Without the token the whole
operator API is a 404, so nothing could show or lift a lock; it is inert like the rest. The
submit check and the reaper rule above then do nothing, the rows stay in the database, and the server
prints one line at startup: N org locks are not enforced: PRINTAPI_OPERATOR_TOKEN is unset. Set the
token again and they hold again.
POST /operator/orgs/{id}/unlock ({reason?}) deletes the row; 409 if the org is not locked.
GET /operator/orgs and the org detail show the lock (locked, status: "locked", lock).
Rolling back to an older version drops the lock. Versions before this one (and the Python server of v2.x) do not read
org_locks: a locked org can submit again, and the table is kept untouched. Unlock first, or accept that. Deleting an org there also leaves its lock row behind; a later org that reuses the id is not locked by it, because the row names the old org's generation.
{reason, confirm}: confirm must equal the org's current name exactly, otherwise 400. The
default org is never removed (400). The org's jobs, printers, agents, keys, accounts, label
templates, terms history and its org_locks row go with it; the audit rows stay. The WAL is
truncated after the commit, so removed payloads do not linger in the -wal file.
{name, email, reason?} creates the org with the signup quota (PRINTAPI_SIGNUP_QUOTA, as a
self-signup would get) and its first user. The user's password hash is that of 32 random bytes,
never NULL, so a login attempt reveals nothing; the reset mail is the invitation, sent after
the commit. Answer: {"ok": true, "org_id", "user_id", "mail_sent"}. Without mail (SMTP_HOST) and
PUBLIC_URL the answer is 409 mail is not configured and nothing is created; a taken address is
409 too. If the mail server fails after the commit, the org stays, mail_sent is false and a
user.reset_mail_failed row is written: use the reset below to send it again.
{org_id, reason?} sends a password-reset mail to the user and never returns the token. org_id
must be the user's org (409 otherwise) and org_created_at that org's generation (409
the org changed, reload), so a stale page cannot reach a user that reuses an id. 409
mail is not configured without mail and PUBLIC_URL; 502 if the mail did not go out (the row
user.reset_mail_failed says so). A user without an e-mail address (the seeded legacy one) is 404.
{org_id, org_created_at, reason?} revokes an API key (409 if the key belongs to another org or
generation). Agents enrolled
with it end their long-poll with 401. Removing a single user is not offered here: customers remove
their own accounts, and root still can.
Four settings can be changed while the server runs, so the console does not need a restart or
shell access. They are start values read from the environment; with PRINTAPI_OPERATOR_TOKEN set,
an override stored in the database applies on top of them.
| Key | Value | Env variable it overrides |
|---|---|---|
signup |
"open" or "closed" |
PRINTAPI_SIGNUP |
signup_quota |
integer, 0 or more (0 blocks printing) | PRINTAPI_SIGNUP_QUOTA |
job_retention_days |
integer, 1 or more | PRINTAPI_JOB_RETENTION_DAYS |
terms |
{"version", "terms_url", "dpa_url"?, "privacy_url"?}, a non-empty version without control characters, at most 100 characters, http(s) links without spaces, terms_url required |
PRINTAPI_TERMS_VERSION and the three link variables |
The values follow the rules of the environment variables. They apply to the next request, with no
restart: the signup form, GET /health, POST /operator/orgs (the quota of the new org) and the
next retention pass read them.
{
"settings": {
"signup": {"value": "closed", "source": "env-locked"},
"signup_quota": {"value": 50, "source": "db"},
"job_retention_days": {"value": null, "source": "default"},
"terms": {"value": {"version": "2026-11", "terms_url": "https://example.com/terms"}, "source": "env"}
},
"env_only": {
"fetches_per_org": 4, "private_urls": "deny", "trusted_proxies": ["10.0.0.0/8"],
"operator_from": ["10.9.0.2"], "public_url": "https://print.example.com", "mail": true
}
}source says where the effective value comes from:
db: an override of the operator API.env: the environment variable is set.default: neither (valueis"closed"forsignup,nullfor the others).env-locked:signuponly, see the emergency brake.
A key also has ignored, the stored row value, when a row exists but is not applied: signup is
env-locked, a signup row of open while private URLs are allowed, or a value that no longer
validates. It is absent otherwise. unset clears such a row.
env_only shows the settings that stay in the environment, as they were at startup. It never
holds a token, a password or a key.
{"set": {key: value}, "unset": [key], "reason"?}. set changes a key, unset removes the
override so the environment value (or the default) applies again. There are no null values.
Everything is checked first and written in one transaction with one audit row; the answer is the
same as GET. reason is optional, at most 500 characters.
| Status | Why |
|---|---|
400 |
an unknown key or field, a key in both set and unset, an empty request, a null, a value that fails the rules above, a bad reason, or a missing reason (see retention) |
409 |
signup is locked by the environment and the change sets open, or the change (a set or an unset of signup) would leave signup open while private URLs are allowed. A PUT that does not touch signup is never refused for this |
401 |
not the operator token, or not from an address in PRINTAPI_OPERATOR_FROM (root does not pass) |
404 |
PRINTAPI_OPERATOR_TOKEN is not set |
Audit: settings.update, detail {"set": {key: value}, "unset": [key]}. Setting values are
allowed in the log (a mode, numbers, links); no e-mail address is.
While the operator token is set, any value of PRINTAPI_SIGNUP other than open (closed, but
also CLOSED, off or a typo) locks signup shut and beats every override: source is
env-locked. Only changes that close signup are accepted then: set to closed and unset;
setting open answers 409. Leaving the variable out, or blank, means closed by default and is
not a lock. To shut signup at once even if the console is compromised, set the variable to
closed and restart.
A stored signup row is not applied while locked, but it stays in the database and shows as
ignored. Clear it (unset or set to closed) before lifting the brake, or it applies again
once the variable is removed.
Retention is the one irreversible setting: the next pass scrubs payloads and titles for good, and
at once if retention was off. A set of job_retention_days that lowers the effective value, or
turns it on while jobs were kept for ever, needs a reason of at least 8 characters (400
otherwise). So does an unset that falls back to a lower or enabled environment value. Raising
it needs none.
fetches_per_org, private URLs (PRINTAPI_PRIVATE_URLS) and trusted proxies decide what the server may reach and whose address it believes. They are fixed at startup, and the livesignupvalue never moves them: hosted mode keeps the private-URL deny whether signup is open or closed. A change that leaves signup open is refused (409) while private URLs are allowed.PRINTAPI_OPERATOR_FROMand the token are the gate itself: a console must not be able to widen who can reach it.- SMTP and
PUBLIC_URLhold credentials and the address links in mails point to.
Only with the operator token set does the server read the settings table; without it every
value is the environment one, as in 3.5.0, and a database carried over from a hosted box changes
nothing. At startup each applied override prints one line to stderr (never a secret). A stored
value that no longer validates is ignored with a line, and so is signup = open while private
URLs are allowed or PRINTAPI_SIGNUP locks signup shut. Values in these lines are quoted. An older
version ignores the table, so the environment values apply again after a rollback; the table is
left in place.
Support access lets the operator read what the customer's jobs contain, for a limited time, with
the customer able to see every access. Without it the operator API never shows a job title or
payload. It is on whenever the operator token is set; features lists support.
A grant covers a whole org for 15, 30 or 60 minutes. An org has at most one active grant at a
time. A grant is active while it is not ended, not expired and was made for the org's current
generation (org_created_at): an org deleted and recreated under the same id does not inherit it.
An expired grant that was never ended does not block a new one.
{reason, minutes, org_created_at}: reason is 8 to 500 characters, minutes is 15, 30 or
60 (400 otherwise), org_created_at is the generation the page showed (409
the org changed, reload). 404 for an unknown org, 409 when the org already has an active
grant. Answers the grant: {id, reason, granted_at, expires_at}.
Optional {reason}. Ends the grant now, by its id alone, so a stale page cannot fail it. 404 for
an unknown grant, 409 when it is already ended or expired.
Answers the stored payload as raw bytes. It is a POST so that no prefetch and no embedded URL can
trigger the read; no body is needed. 403 no active support access when the job's org has no
active grant, 404 for an unknown job, 410 when the retention pass has already emptied the
payload (see PRINTAPI_JOB_RETENTION_DAYS). The response is built so a browser never renders it:
Content-Type: application/octet-stream, Content-Disposition: attachment; filename="job-<id>.pdf" (.bin unless the job's mode is pdf), X-Content-Type-Options: nosniff,
Content-Security-Policy: sandbox; default-src 'none' and Cache-Control: no-store. If the audit
row cannot be written the answer is 500 and no bytes are sent.
Titles are opt-in. Without titles=1 the list is the metadata of the jobs endpoint,
whatever the grant state, and writes nothing: a tab that refetches does not fill the log or the
customer's card. With titles=1 and no active grant the answer is 403 no active support access.
With an active grant each job also carries its title. A full page always offers
next_before_id; the page after the last one is empty.
| Action | When | detail |
|---|---|---|
support.grant |
a grant is made | {"minutes": n} |
support.end |
a grant is ended | none |
support.list_jobs |
a titled page with at least one job is returned | {"job_ids": [...]} |
support.read_job |
a payload is returned | {"job_ids": [id]} |
Every row has target grant:<id> and the org it concerns. Each titled page and each payload
read also adds one to the grant's reads. The rows hold ids only: no e-mail address, name, title
or payload. Each of these writes is one transaction with its audit row.
The customer's Settings page lists every grant of their org that was used, and the 50 newest
unused ones: reason, when it started, when it expires or was ended, and the ids of the jobs the
operator listed and opened. So a run of empty grants cannot push an access out of view. The grants
stay for ever like the audit log; deleting an org removes its grants, and the audit rows stay. The
dashboard reads them from GET /support-access.