Control plane

The control plane (api-next) is the one central service Potter runs. It is the source of truth for who is entitled to what and where each box lives.

Responsibilities

• Licensing. Mint license keys, exchange a key for a short-lived activation token (RS256 JWT), and publish the public key the gated registry uses to verify those tokens.
• Deployment registry. Register a box’s domains, provision DNS through the domain provider, and return the nameserver records the vendor delegates.
• Host routing. Resolve a public host to the bank engine backend that serves it (consumed by the storefront render app).
• Telemetry. Accept package-download events reported by the gated registry.

What it does not do

• It does not run merchant traffic — that is the engine in each box.
• It does not serve packages — that is the gated registry (box-registry), which trusts the control plane’s signing key.
• It does not render storefronts — that is the shared render app (web).

Trust model

The activation JWT is the single credential that travels from the control plane, through the box, to the registry. Because the registry verifies it against the control plane’s published key, no shared secret has to be distributed to boxes.

Sections

• API reference — every endpoint, auth, request, and response.
• Licensing — key lifecycle, activation, JWT claims, JWKS.
• Deployment — registering box domains and DNS delegation.