openclaw-mission-control/docs/07-api-reference.md

API / auth

This page documents how Mission Control’s API surface is organized and how authentication works.

For deeper backend architecture context, see:

• Architecture

Base path

Evidence: backend/app/main.py.

• All API routes are mounted under: /api/v1/*

Auth model (two callers)

Mission Control has two primary actor types:

1. User (Clerk) — human UI/admin
2. Agent (X-Agent-Token) — automation

User auth (Clerk)

Evidence:

• backend: backend/app/core/auth.py

• config: backend/app/core/config.py

• Frontend calls backend using Authorization: Bearer <token>.

• Backend validates requests using the Clerk Backend API SDK with CLERK_SECRET_KEY.

Agent auth (X-Agent-Token)

Evidence:

• backend/app/core/agent_auth.py

• agent API surface: backend/app/api/agent.py

• Agents authenticate with X-Agent-Token: <token>.

• Token is verified against the agent’s stored agent_token_hash.

Route groups (modules)

Evidence: backend/app/main.py includes routers from backend/app/api/*.

Module	Prefix (under /api/v1)	Purpose
activity.py	/activity	Activity listing and task-comment feed endpoints.
agent.py	/agent	Agent-scoped API routes for board operations and gateway coordination.
agents.py	/agents	Thin API wrappers for async agent lifecycle operations.
approvals.py	/boards/{board_id}/approvals	Approval listing, streaming, creation, and update endpoints.
auth.py	/auth	Authentication bootstrap endpoints for the Mission Control API.
board_group_memory.py	/board-groups/{group_id}/memory and /boards/{board_id}/group-memory	Board-group memory CRUD and streaming endpoints.
board_groups.py	/board-groups	Board group CRUD, snapshot, and heartbeat endpoints.
board_memory.py	/boards/{board_id}/memory	Board memory CRUD and streaming endpoints.
board_onboarding.py	/boards/{board_id}/onboarding	Board onboarding endpoints for user/agent collaboration.
boards.py	/boards	Board CRUD and snapshot endpoints.
gateway.py	/gateways	Thin gateway session-inspection API wrappers.
gateways.py	/gateways	Thin API wrappers for gateway CRUD and template synchronization.
metrics.py	/metrics	Dashboard metric aggregation endpoints.
organizations.py	/organizations	Organization management endpoints and membership/invite flows.
souls_directory.py	/souls-directory	API routes for searching and fetching souls-directory markdown entries.
tasks.py	/boards/{board_id}/tasks	Task API routes for listing, streaming, and mutating board tasks.
users.py	/users	User self-service API endpoints for profile retrieval and updates.

Backend API layer notes (how modules are organized)

Evidence: backend/app/main.py, backend/app/api/*, backend/app/api/deps.py.

Conventions

• Each file under backend/app/api/* typically declares an APIRouter (router = APIRouter(...)) and defines endpoints with decorators like @router.get(...), @router.post(...), etc.
• Board-scoped modules embed {board_id} in the prefix (e.g. /boards/{board_id}/tasks).
• Streaming endpoints usually expose SSE endpoints at .../stream (see sse-starlette usage).

Where key behaviors live

• Router wiring / base prefix: backend/app/main.py mounts these routers under /api/v1/*.
• Auth / access control is mostly expressed through dependencies (see backend/app/api/deps.py):
  • require_admin_auth — require an authenticated admin user.
  • require_admin_or_agent — allow either an admin user or an authenticated agent.
  • get_board_for_actor_read / get_board_for_actor_write — enforce board access for the calling actor.
  • require_org_member / require_org_admin — enforce org membership/admin for user callers.
• Agent-only surface: backend/app/api/agent.py uses get_agent_auth_context (X-Agent-Token) and contains board/task/memory endpoints specifically for automation.

Module-by-module map (prefix, key endpoints, and pointers)

This is a “where to look” index, not a full OpenAPI dump. For exact parameters and response shapes, see:

• route module file (backend/app/api/<module>.py)
• schemas (backend/app/schemas/*)
• models (backend/app/models/*)
• services (backend/app/services/*)

Module	Prefix (under /api/v1)	Key endpoints (examples)	Main deps / auth	Pointers (schemas/models/services)
activity.py	/activity	GET /activity (events); GET /activity/task-comments + /stream	require_admin_or_agent, require_org_member	app/models/activity_events.py, app/schemas/activity_events.py
agent.py	/agent	agent automation surface: boards/tasks/memory + gateway coordination	get_agent_auth_context (X-Agent-Token)	backend/app/core/agent_auth.py, backend/app/services/openclaw/*
agents.py	/agents	agent lifecycle + SSE stream + heartbeat	org-admin gated for user callers; some endpoints allow agent access via deps	app/schemas/agents.py, app/services/openclaw/provisioning_db.py
approvals.py	/boards/{board_id}/approvals	list/create/update approvals + /stream	require_admin_or_agent + board access deps	app/models/approvals.py, app/schemas/approvals.py

Where authorization is enforced

Evidence: backend/app/api/deps.py.

Most route modules don’t “hand roll” access checks; they declare dependencies:

• require_admin_auth — admin user only.
• require_admin_or_agent — admin user OR authenticated agent.
• get_board_for_actor_read / get_board_for_actor_write — board access for user/agent.
• require_org_member / require_org_admin — org membership/admin for user callers.

“Start here” pointers for maintainers

• Router wiring: backend/app/main.py
• Access dependencies: backend/app/api/deps.py
• User auth: backend/app/core/auth.py
• Agent auth: backend/app/core/agent_auth.py
• Agent automation surface: backend/app/api/agent.py