Node API

Every node of a fleet serves the same API, because the registry is in the bucket and any node can answer any call. Failures are RFC 9457 problem documents with content-type: application/problem+json; see /reference/errors.

Every route but /.well-known/scafo/health requires a token: a node, operator or workload token, or — on the storage and routing surfaces — the ingress token.

#Authentication

#Node and operator tokens

One scheme covers both: a machine and an operator are the same caller to the verifier. The token is a compact JWS presented as Authorization: Bearer <token>.

Every rejection is auth-invalid (401), whatever the cause — a wrong signature, an expired token, a missing header and an unknown kid are indistinguishable to the caller.

Routes marked operator token additionally require kid to name an operator record, and re-read that record on every request, so a revoked or replaced key cannot administer durable authority from a cache. A node token on those routes is auth-scope (403). Routes marked admin operator require role: "admin".

Operator tokens carry an application scope: *, exact names, or prefix globs such as shop-*. A call naming an application outside it is auth-scope, with a detail that never discloses which applications the key does reach. Reads narrow instead of refusing and set scoped: true in the answer.

#Workload OIDC tokens

Accepted on the deploy routes only, and only for an application whose trust policy names the token's iss. Presented in the same Authorization: Bearer header.

A token that does not hold up is auth-invalid. A token that does hold up but whose issuer or subject the policy does not admit is trust-mismatch (403) — the one rejection that is authorization rather than authentication, and the one a CI job can act on.

#Ingress token

An opaque bearer token, compared against the node's admitted token list with a timing-safe comparison. It guards /v1/storage/** and /v1/ingress/routes* and nothing else. A node mints one at boot unless ingress.token names some — --ingress-token once per token, SCAFO_INGRESS_TOKEN comma-separated, or the config file — in which case all of them are admitted and the first is written to the state directory's ingress-token file.

Storage requests may also carry X-Scafo-Storage-Version: 1. An absent or empty header means version 1; any other value is invalid-input.

#Route table

The storage and routing routes exist only when the node has a storage service configured, which is always the case under scafo sail.

Every JSON control request body is bounded by api.jsonBytes (default 65 536). A content-length above it, or a stream that grows past it, is resource-limit (413) and the body is cancelled rather than aggregated.

#Health

#GET /.well-known/scafo/health

Public. No parameters.

{ "ok": true, "version": "0.1.0", "node": "vps-a" }

An application's process answers its own health at /.well-known/celld/health, which is a different endpoint on a different port.

#Certificates

No route of the node decides which names get a certificate. The ingress decides from the routing document it already polls at /v1/ingress/routes: the hosts that document names exactly are the hosts that may get a certificate, and no other. Caddy's tls.permission.scafo approves an on-demand certificate only for a name some fleet's current document names as an exact route host or an API host; Traefik, told a certificate resolver, obtains what the rendering asks for on each router — its exact host, or the tls.domains wildcard certificate that covers it.

Which hosts the routing document names, and so which may get a certificate:

#State

#GET /v1/state

Node and admin-operator callers receive the whole document. A non-admin operator receives it filtered to the applications its key reaches, with scoped: true set.

DaemonState fields:

CoordinatorView fields:

#Applications

Every route takes a :name path parameter and enforces operator application scope before any I/O. There is no create route: the first deploy creates the application, and every setter here refuses a missing one with not-found.

Two boundaries stand in front of them. The reading, admin and domain routes answer operator tokens only; a node token on one is auth-scope. The four setters and the delete route answer operator and node tokens alike, because a node forwards a deletion to the coordinator under its own token — an operator's scope is still applied to the name.

Every route but the listing, the domain routes and the delete answers { "application": ApplicationRecord }.

#GET /v1/applications

{ "applications": [ /* ApplicationRecord */ ], "scoped": true }

Applications are returned in name order. An admin sees full records. A non-admin operator sees only the applications its key reaches, with the fleet-owned labels field removed and scoped: true set; blocked remains visible.

#GET /v1/applications/:name

Operator token. Answers one record, with the same tenant redaction. An application the key cannot reach is auth-scope; one that does not exist is not-found.

#POST /v1/applications/:name/block, POST /v1/applications/:name/unblock

No body. Admin only — application scope is checked first, then the admin tier. Blocking is one CAS update; reconciliation stops serving the application on each node's next pass, its hosts leave ingress, it gets no certificates and it accepts no deploys. Nothing is deleted, and unblocking restores the prior desired state. Each emits one observability event naming the actor.

#POST /v1/applications/:name/labels

Admin only. Body:

{ "labels": { "account": "acme", "plan": "pro" } }

labels must be a JSON object of string values; an empty object clears them. Labels are replaced wholesale and are never interpreted by scafo. A missing application is not-found.

#POST /v1/applications/:name/retire

No body. One CAS update; it does not require coordinator authority.

#POST /v1/applications/:name/unretire

No body. Retirement is reversible during its grace period.

#POST /v1/applications/:name/selector

Body (JSON, ≤ api.jsonBytes):

{ "selector": { "region": "eu-west-1", "tier": "fast" } }

"selector": null clears the constraint. Omitting selector entirely is invalid-input. An unsatisfiable selector is valid and is reported by assignment, not rejected here.

#POST /v1/applications/:name/replicas

Body (JSON, ≤ api.jsonBytes):

{ "replicas": "all" }

replicas must be given: "all", or a whole number of at least 1. Omitting it, or sending null, is invalid-input — there is no default. The coordinator acts on it on its next assignment pass.

#POST /v1/applications/:name/domains/:host[?wildcard=1], DELETE /v1/applications/:name/domains/:host

No body. Operator token only — a node token, and the workload token a deploy pipeline holds, are both auth-scope: a pipeline publishes an application, it does not decide what the fleet answers on.

:host is the host itself, lowercased and held to the claim rule: fully qualified, at most 253 characters, at least two labels of 1–63 characters from [a-z0-9-] not starting or ending with a hyphen, a last label that is not all digits, and no wildcard, port, scheme, path, trailing dot or underscore. Anything else is invalid-input naming the rule. A host equal to or under one of this node's platform domains is invalid-input too: every host there is rendered from an application's name.

?wildcard=1 on the POST claims the single label below the host as well. Only 1 counts. It additionally requires a key whose scope reaches <name>-*, since the claim also decides what <name>-<env> answers on; a key that does not is auth-scope.

Both answer:

{ "application": { /* ApplicationRecord */ }, "host": "shop.example", "platformHosts": ["shop.apps.example.com"] }

platformHosts is where the application answers under this installation's own domains, and is empty when it serves no platform domain.

Re-claiming a host the same application already holds is idempotent, and a claim that already covers its subdomains is never downgraded by a later POST that leaves wildcard out. Writes go referent-first — the application is checked, the claim is created, then the application lists the host — so a crash in between leaves a claim nothing routes to, which re-running the call repairs.

#DELETE /v1/applications/:name[?force=1]

Only force=1 and force=true count as forced; anything else reads as not forced. Forcing skips both the retirement and the grace requirement.

Deletion is coordinator-gated: S3 has no conditional delete, so the lease is the only thing keeping two deleters apart. Any node accepts the request:

• This node holds the lease → it does the work.
• Nobody holds it → this node offers itself once, then does the work or finds out who won.
• Another node holds it → the request is forwarded there once, under a fresh node token this node signs for itself, and the coordinator's answer is returned verbatim, problem document included.

#Deploys

#POST /v1/applications/:name/deploys

The artifact is the raw request body, content-type: application/octet-stream, streamed to a file and bounded by deploy.artifactBytes in both compressed and expanded form.

Everything else travels in one header:

The encoding is checked strictly: the header must match ^[A-Za-z0-9_-]+$, decode as valid UTF-8 JSON, and re-serialize to exactly the bytes given (stable key order, no padding). Anything else is invalid-input, Malformed request.

Metadata fields:

Three names are refused outright, each invalid-input, Malformed request:

Anything else the document carries is ignored: the header is read for the fields above and nothing else. The document itself must still be a JSON object, and so must source when given; anything else is invalid-input.

The artifact's own runtime configuration is not read here at all. The node locates wrangler.jsonc, then wrangler.json, at the archive root, refuses an artifact carrying neither with invalid-input, and hands that path to Celld untouched — which is why there is no metadata field for a script name, for bundling, or for a version to record the deployment under. scafo deploy --var and --no-bundle edit the config client-side, before the directory is packed.

The caller is authenticated before the metadata header or the body is read.

The order matters: the freeze is read first, then the application is created — or, when it already exists, checked for a block and updated with any placement intent the metadata carried — and then the Celld versions are compared. Only after all three does the artifact body begin to be read.

Everything after the 202 — the artifact's configuration among it — is reported on the deploy's own record, not here.

#GET /v1/deploys/:id

Answers DeployStatus:

A deploy id is <name>.<16 hex>, and every state a deploy enters is a registry record under that application. Any node answers a poll, so it may land wherever an ingress sends it, and a restart of the accepting node loses nothing. The application in the id is what the caller is authenticated against, exactly as the upload was.

An id that is no deploy id names no application, so the caller is verified against a null application first and the answer is 404 not-found. A record filed under an id whose application half it disagrees with is 404 too.

A deploy nobody is carrying out any more is judged at read time. A record that is not terminal, has not moved for a whole 90-second liveness window, and whose accepting node is not answering is returned as failed with code: "deploy-timeout" and a detail naming that node — without waiting for a sweep and without writing anything, because a poll is a read. It costs one extra read, and only in that one case. The coordinator's reaper records the same judgement, with the same code and the same detail, on its next pass; it also deletes terminal records after seven days.

#Operators

#GET /v1/operators

{ "operators": [ /* TrustedOperator */ ], "scoped": true }

Keys are returned in id order. An admin sees every key. A non-admin operator sees only its one-step rotation lineage — itself, the key it supersedes, and any key that supersedes it — and the answer carries scoped: true.

#POST /v1/operators

Body (≤ api.jsonBytes):

{
  "id": "op-9f3c",
  "publicKey": { "kty": "OKP", "crv": "Ed25519", "x": "..." },
  "role": "operator",
  "supersedes": "op-1a2b",
  "applications": ["shop", "shop-*"]
}

Authorization rules, each answered auth-scope (403):

• A supersedes naming anything but the caller's own id.
• Registering a tier the caller may not grant.
• Registering a scope reaching past the caller's own.
• Granting * when the caller is not an admin. An operator-tier key may replace itself with a wildcard key, but may not hand one out beside itself.

A fresh grant additionally requires an explicit scope. Replacements are idempotent, so an interrupted rotation can be repeated.

Answers { "operator": TrustedOperator }.

#DELETE /v1/operators/:id

Answers { "removed": "<id>" }.

#Fleet

Statements an admin makes about the installation itself rather than about one application.

#POST /v1/fleet/freeze

Admin only. Stops deploy intake for the whole fleet; every node refuses POST /v1/applications/:name/deploys with deploys-frozen (409) until it is lifted. Nothing else changes — serving, reconciliation, retirement and application deletion all carry on.

The body is optional. A freeze with nothing to say is a POST with no body at all; a body, when there is one, is a JSON object:

{ "reason": "moving every node to a new Celld release" }

Anything else is invalid-input. by is the caller the guard verified, never anything the body said.

Answers:

{ "freeze": { "v": 1, "frozenAt": "…", "by": "op-9f3c", "reason": "…" }, "created": true }

created is false when deploys were already frozen, in which case the first freeze comes back unchanged: freezing twice is one freeze, and neither the stamp nor the reason moves.

#DELETE /v1/fleet/freeze

Admin only. No body. Answers { "lifted": boolean } — false when there was no freeze to lift. Nodes take deploys again on the next intake.

#GET /v1/fleet/freeze

Readable by any operator of the fleet, whatever its tier: whoever is refused a deploy is owed the reason. Answers { "freeze": FreezeRecord }, or 404 not-found, Deploys are not frozen, when this fleet holds no freeze record.

A non-admin key on the two writing routes is auth-scope (403), and the detail says freezing is a decision the fleet makes about itself rather than one taken inside an application.

#Storage

Behind the ingress token. A key is everything after /v1/storage/objects/, separators included, and is spelled back to the caller exactly as it was given.

Values are read and written as bytes, never as text. recursive is truthy only for true and 1; anything else lists the immediate children. An empty listing is a 404, not an empty array: the caller's storage contract requires a missing prefix and an existing empty one to be distinguishable.

Lock acquisition is try-acquire and never waits: a held name answers 409 cas-conflict. Release is idempotent. Keys and lock names must be relative, printable ASCII, with no empty, . or .. segment; anything else is invalid-input.

#Ingress routing

#GET /v1/ingress/routes[?prefer=<node>|self]

Answers the generic FleetRouting document as of the last reconcile pass. prefer is read here exactly as it is on the format route below.

#GET /v1/ingress/routes/:format[?prefer=<node>|self]

Answers the routing in a format the ingress reads natively. Only traefik is registered. An unknown format is 404 not-found, and the detail names the formats this node renders.

?prefer=<node-id> puts that node's upstreams first on every route. ?prefer=self means the node being asked, so a colocated ingress never has to know the node's id. A node that serves nothing is preferred to no effect. Omitting the parameter asks for the fleet's own order.

Both routes refuse with 503 draining until this node's first reconcile pass has completed — an empty document would read as every route in the fleet withdrawn, where a refusal is a pause the ingress rides out on the last document that parsed.