API Authentication

Automation is a first-class citizen of the mesh — but it must authenticate like one: with scoped credentials that can be rotated or revoked without touching the core mesh identity.

Scoped credentials for automation

Use scoped credentials for automation and avoid broad operator tokens. A build pipeline does not need enrollment rights; a monitoring script does not need ACL write access. Credentials should map to organization, product, and environment boundaries so an integration can be rotated or revoked without affecting anything else — and so the audit trail can say exactly which token did what.

Representative scoped token request

  # create a token scoped to the builders team, git surface only
  POST /v1/auth/tokens
  {
    "name": "ci-runner-main",
    "scope": { "team": "builders", "surface": "git", "environment": "production" },
    "expires": "2026-11-01T00:00:00Z"
  }

Coordinator REST API under /v1

The coordinator exposes its control plane under /v1: auth, nodes, peers, ACLs, relays, ingress, MeshCA, firewall, telemetry, snapshots, monitoring, and WAF. The dashboard proxies these same APIs — anything you can do in the UI, automation can do through the API, under the same RBAC and method-level permissions.

Representative coordinator call

  curl -s https://coordinator.rizoma.mesh/v1/nodes \
    -H "Authorization: Bearer <scoped-token>" \
    -H "Accept: application/json"

Webpanel API under /api/v1

Webpanel's management API lives under /api/v1 and secures itself with session cookies, CSRF protection, rate limits, and RBAC, with Prometheus metrics for the API surface itself. Where the coordinator serves machine-to-machine automation, Webpanel is designed for browser sessions and administrative tooling — use session flows for humans, scoped tokens for scripts.

Both surfaces expose health endpoints (healthz, readyz) so load balancers and monitoring can distinguish a running process from a ready service.

Rotation and revocation

Plan rotation as part of the integration, not as an incident response. Tokens with expiration dates force renewal on a schedule; revocation must be possible without touching the core mesh identity — revoking a scoped token should never require re-enrolling nodes or reissuing certificates. When an integration's scope changes, issue a new token and retire the old one the same day.

Broad tokens are incident reports in waiting. If a compromise forces you to rotate everything because one token could do everything, the token was the problem. Scope first, rotate often, and let the audit trail verify both.

Previous Audit & Logging Next Node Management