Skip to content

API

JANUS is API-first: the WebUI and the Self-Service Portal are themselves API clients, and every operation they perform is available over the Management API.

The one sentence to remember

Git is the source of truth. The API authors desired-state changes into Git and reads runtime and observability state back out; it never becomes a second source of truth.

No OpenAPI description ships in this release

This release ships no OpenAPI document. There is nothing to generate a reference from, and none is provided. The endpoint list on this page is the supported surface. Anything not listed here is not part of the supported API, even if a path exists internally.

Shape of the API

  • All routes are under /api/v1/…, plus the unversioned health endpoints.
  • Responses are JSON unless stated otherwise.
  • Management routes are registered as a path with the HTTP methods dispatched inside the handler. The path is what is guaranteed; where a method set is documented below it is the one the handler implements.
  • Errors are returned as a structured JSON body with an error code and message.

Authentication

Authentication endpoints are public (reachable without a prior session):

Path Purpose
/api/v1/auth/methods The authentication providers this installation offers.
/api/v1/auth/local/login Janus Local login.
/api/v1/auth/break-glass/login Break-glass login, using the host-enabled recovery credential only.
/api/v1/auth/logout Logout; clears the session cookie.
/api/v1/auth/oidc/start OIDC authorization start.
/api/v1/auth/oidc/callback OIDC authorization callback.
/api/v1/whoami The authenticated caller. Requires an authenticated principal.

Authentication establishes a session (browser) or an API token (non-interactive) and identifies the principal. It grants nothing by itself.

Authorization model

Authorization is evaluated on every request by one central authorizer. The model has three parts:

  • Permission — a named capability (for example gateway:read, operation:read, audit:read, config:read, principal:admin).
  • Role — a named set of permissions. Roles are built in and listed at /api/v1/roles.
  • Binding — links a principal to a role in a scope. A platform-scoped binding covers the platform; a tenant-scoped binding covers that tenant's deployments without reading Git per request.

A route declares the protection it needs:

Protection Meaning
public No session required (health, login, initial onboarding).
principal An authenticated principal is required.
gateway machine The gateway machine-trust channel (mutual TLS or bootstrap trust).
gateway signed The request is signed with the gateway identity.

and, where relevant, a scope: platform, service (authorization inside the application service), authenticated-only, or handler-authorized (the handler resolves the caller's effective scope and evaluates the permission itself).

No route accepts another user's identifier

The self-service routes derive the effective user from the authenticated session's principal–user link. A client-supplied user or owner id can never select another user's scope.

CSRF for state-changing browser calls

A browser request that changes state must present a session-bound CSRF token in addition to its session. A missing or mismatched token is rejected. This applies to the WebUI's mutating routes and to the portal's state-changing methods (safe methods such as GET, HEAD and OPTIONS are session-gated but exempt from the token check).

Health and readiness

Path Protection Purpose
/healthz public Liveness. Returns ok.
/readyz public Readiness. Returns {"ready": bool, "lkg": "…"}.

Identity and administration

These require a principal and, except for /api/v1/whoami, the principal:admin permission at platform scope:

Path Purpose
/api/v1/whoami The authenticated caller.
/api/v1/principals List principals, or create an end-user principal with a local credential.
/api/v1/principals/ Principal state, bindings and identity links.
/api/v1/bindings List bindings.
/api/v1/bindings/ Delete a binding.
/api/v1/roles List built-in roles.
/api/v1/tokens List and create API tokens.
/api/v1/tokens/ Revoke an API token.
/api/v1/sessions List sessions.
/api/v1/sessions/ Revoke a session.
/api/v1/break-glass Break-glass state.
/api/v1/bootstrap/status Bootstrap state.

Management reads

Path Permission Purpose
/api/v1/gateways gateway:read (platform) List gateways.
/api/v1/deployments handler-authorized List deployments filtered to the caller's authorized set, or create a deployment with platform authority.
/api/v1/operations operation:read (platform) List management operations.
/api/v1/audit audit:read (platform) List audit events.

Desired-state authoring

Path Purpose
/api/v1/deployments/ Deployment-scoped config authoring. Authorization is enforced inside the application service.
/api/v1/config/validate Whole-state validation.
/api/v1/config/plan Compiled plan.
/api/v1/config/schema Kind field schema.

The three /api/v1/config/* routes require config:read at platform scope.

Platform-scope control-plane authoring

Path Purpose
/api/v1/platform/config/ Tenant, Deployment, GatewayNode and placement authoring.
/api/v1/platform/gatewaynodes/ Platform GatewayNode runtime domains. Requires platform gateway:read.

Gateway machine endpoints

Preserved machine-trust channel between a gateway and the controller:

Path Protection Purpose
/api/v1/gateway/register gateway machine Gateway registration.
/api/v1/gateway/heartbeat gateway machine Gateway heartbeat.

Node enrollment

Path Protection Purpose
/api/v1/gateway-enrollment/requests public, signed Create a pending enrollment record only; grants nothing.
/api/v1/gateway-enrollment/status gateway signed Enrollment status.
/api/v1/gateway-enrollment/heartbeat gateway signed Gateway liveness.
/api/v1/gateway-enrollments principal, gateway:read List enrollment trust records.
/api/v1/gateway-enrollments/ handler-authorized Read, approve, reject or revoke an enrollment record.

The request endpoint is reachable by a gateway with no prior trust but is authenticated by the gateway's own signature; the administrative surface is principal-protected. This is the surface the janus operator CLI uses.

Client access enrollment

Path Protection Purpose
/api/v1/client-enrollment/requests public, bearer invitation Create one declared Device from a single-use, expiring, deployment-scoped bearer invitation.
/api/v1/access-invitations/redeem public, bearer invitation The same access-trust credential, redeemed by a human: it additionally lets the invited user establish their own portal credential, and returns the client profile. Every failure is uniform.
/api/v1/client-enrollments handler-authorized List and create client enrollment invitations.
/api/v1/client-enrollments/ handler-authorized Revoke a client enrollment invitation.

Self-service API

The self-service surface is used by the user portal. Every route is principal-protected and handler-authorized, and every route accepts an optional ?deployment=<name> selector that must be one of the caller's own links.

Method and path Purpose
GET /api/v1/self/profile The caller's self-service scope and linked deployments.
GET /api/v1/self/devices List the caller's own devices.
POST /api/v1/self/devices Enrol a device: name, publicKey (required) and optional displayName/deployment.
GET /api/v1/self/devices/{name} Device detail and profile.
PATCH /api/v1/self/devices/{name} Rename or change the display name ({name?, displayName?}).
DELETE /api/v1/self/devices/{name} Retire the device (declarative delete).
POST /api/v1/self/devices/{name}/revoke Disable the device (idempotent).
POST /api/v1/self/devices/{name}/restore Re-enable the device (idempotent).
GET /api/v1/self/devices/{name}/config The client configuration response: profile, assembled configuration and manifest.

The enroler supplies only a name and a public key. The server builds the whole Device declaration itself — owner, addresses, gateway and enabled state — so self-authorization is impossible by construction. When self-service is not configured, these routes answer 503.

Site Edge signed-request endpoints

The Site Edge and the controller exchange signed requests. The path is part of the signed canonical string, so both sides use the same constants.

Path Purpose
/api/v1/site-edge/bootstrap/start Begin outbound bootstrap; a public endpoint that grants nothing.
/api/v1/site-edge/bootstrap/finish Complete bootstrap.
/api/v1/site-edge/participant/profile Deliver the participant profile to the edge.
/api/v1/site-edge/participant/ack Revision-correlated acknowledgement from the edge.
/api/v1/site-edge/participant/observed Observed state reported by the edge.
/api/v1/deployments/{deployment}/siteedges/{edgeName} A Site Edge object in a deployment.
/api/v1/deployments/{deployment}/siteedges/{edgeName}/revoke Revoke the edge's trust.
/api/v1/deployments/{deployment}/siteedges/{edgeName}/runtime Site Edge runtime read model (desired/delivered/applied/observed kept independent). Read-only; authorizes nothing.

Every bootstrap rejection is reported to an unauthenticated caller as one uniform failure, so a caller learns nothing about which records exist.

Bootstrap and onboarding endpoints

These are public because there is no identity yet, and they exist only while setup is required:

Path Purpose
/api/v1/setup/status Initial setup status.
/api/v1/setup/administrator Create the primary administrator (initial setup only).

The handler re-reads the authoritative setup state on every request, so once setup is complete these routes create no accounts. There is no network endpoint that can bootstrap an administrator afterwards: further administration is host-local (see the controller admin commands).