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).
Related¶
- Command-line interface — the tools that call this API
- WebUI — a browser client of this API
- Client — the self-service enrolment and configuration flow
- Configuration — the authored objects