Realms - cliq

control plane

A realm is the Hub unit for a fleet of daemons: membership, desired teams, agent settings, enroll tokens, and (optionally) a public A2A door. Interactive paths: Hub API tab → Realms, Realm teams, Realm agents, Realm A2A, Public A2A.

Resources

Resource	Base paths	What it is
Realm	`/v1/realms/create`, `/get`, `/get_by_id`, `/get_by_slug`, `/update`, `/remove`	CRUD + filtered list
Members	`/v1/realms/members/*`, `/grant`, `/revoke`, `/search_users`	Users / daemons / roles
Invites	`/v1/realms/invites/*`	Email invite create / accept / revoke
Team list	`/v1/realms/team-list/*`	Desired `@scope/slug` set; apply / force sync
Teams inventory	`/v1/realms/teams/get`	What’s installed across daemons + coverage
Agents	`/v1/realms/agents/*`	Per-realm settings pushed on install
A2A admin	`/v1/realms/a2a/*`	Enable, bearer, mesh connect
Public A2A	`GET /a2a/r/{slug}/.well-known/agent-card.json`, `POST /a2a/r/{slug}/send`	Host-root card + JSON-RPC (not under `/v1`)
Runs	`/v1/runs/*` (+ events, logs, phases, artifacts)	Lifecycle and observability for work on realm daemons
Start a run	`POST /v1/dispatch/enqueue` `{ kind: "run", realm_id, payload.team_id }`	Offer → claim → execute (Hub UI path). Pin with `/dispatch/run`.

Enroll tokens are not under /realms/tokens — mint with POST /v1/auth/generate_token { "type": "realm", "realm_id": "…" } (or cliq realm token).

Auth

Who	Credential
Console / CLI / CI	Session JWT or `cliq_tok_…`
Daemon enroll / poll	`cliq_dt_…` realm token
Public `/send`	`cliq_a2a_…` bearer (or mesh inbound JWT)

Quick flow

# List realms
curl -s https://api.cliqhub.io/v1/realms/get \
  -H "Authorization: Bearer $USER_JWT" -H "Content-Type: application/json" -d '{}'

# Desired teams
curl -s https://api.cliqhub.io/v1/realms/team-list/add \
  -H "Authorization: Bearer $USER_JWT" -H "Content-Type: application/json" \
  -d '{"realm_id":"…","scope":"@cliq","slug":"hello-world"}'

# Enable A2A + rotate bearer
curl -s https://api.cliqhub.io/v1/realms/a2a/update \
  -H "Authorization: Bearer $USER_JWT" -H "Content-Type: application/json" \
  -d '{"realm_id":"…","a2a_enabled":true}'

curl -s https://api.cliqhub.io/v1/realms/a2a/rotate_bearer \
  -H "Authorization: Bearer $USER_JWT" -H "Content-Type: application/json" \
  -d '{"realm_id":"…"}'

# Public card (no auth)
curl -s https://api.cliqhub.io/a2a/r/$SLUG/.well-known/agent-card.json

See Hub Control Plane for enroll + dispatch. Full schemas live in the Hub API tab.