API reference

The Aroovo platform exposes a JSON-over-HTTP API for every operator action the console performs. All requests are authenticated with a bearer token issued by the Brand's configured identity provider (Entra MSAL token, or a JWT from Google / Okta / Auth0 — see Concepts — BYO identity). Tokens go in the Authorization: Bearer <token> header.

Base URL. https://agents.aroovo.tech for the Aroovo Brand. Each Brand with a verified primaryDomain has its own base URL too — the hostname-routing middleware attaches the Brand context server-side.

Reference groups

The six representative groups below cover the operator surface area most users will touch. Other groups (notifications, broadcast, triggers, costs, marketing, secrets, standups, tasks, teams-channels, team, memory) are routed under the same authentication and shape; they're documented in a later release.

  • Brands — platform-superadmin CRUD over the Brand catalogue plus per-Brand provider / auth / Slack / hostname management.
  • Tenants — Brand-Owner CRUD over the Tenants under their Brand, plus owner invites and tenant health.
  • Agents — per-Tenant agent management: list, patch, pause, resume, archive, restore, chat, KB, usage.
  • Knowledge base — upload and manage KB files, per-agent and tenant-wide.
  • MCP tools — register MCP servers, per-agent allowlists, per-tool approval policies.
  • Audit — the HMAC-chained audit log and the chain-verify endpoint.

Conventions

Every endpoint:

  • Returns 200 on success with a JSON body (objects for single-resource fetches, { items: [...] } for lists).
  • Returns 400 with { error: '<code>', detail?: string } on a validation failure.
  • Returns 403 with { error: 'requires_*' } when the bearer token doesn't carry the role required for the endpoint.
  • Returns 404 with { error: '*_not_found' } when a path parameter resolves to nothing.
  • Returns 409 when the request would violate a uniqueness or lifecycle constraint (e.g. creating a Brand with a slug that already exists, suspending the Aroovo Brand).
  • Returns 429 when the per-tenant rate limit is exceeded.

RBAC roles

The bearer token resolves to a User row with one of these roles:

  • platform-superadmin — the Aroovo Brand Owner. Can manage every Brand.
  • BrandOwner — scoped to one Brand. Manages tenants, auth, theme, provider keys for that Brand only.
  • Owner — scoped to one Tenant. Manages agents, KB, secrets, audit-verify for that Tenant.
  • Admin — reduced Owner; can edit but not delete.
  • Member — can use agents and approve their own tool calls when policy allows.