API Documentation

Every Wildbox service exposes a REST API. In a deployment, clients reach them through the gateway over HTTPS; the routes are listed under Gateway routes.

The endpoint references below are written by hand in the repository. Where one disagrees with a running service, the service is right: please open an issue.

Available APIs

The endpoint references are written by hand and are the published API documentation. For a machine-readable schema, run the service in development: identity, tools, data, responder, agents and cspm serve /openapi.json on their local port when ENVIRONMENT is development, and guardian serves /api/schema/ when DEBUG is on. See also the API documentation index.

Authentication

Obtain a JWT from the identity service with a form-encoded login (fields username and password), then send it as a bearer token. Through the gateway the login path is /auth/jwt/login; the Quick start shows the full, tested sequence. Token lifetime (30 minutes, no refresh), logout and the failed-login lockout are described in Authentication and sessions.

• Authorization: Bearer <access_token> — JWT returned by the login
• X-API-Key: <key> — an API key created through the identity service, accepted by the gateway as an alternative

Gateway routes

The gateway is the only service published beyond the local machine: HTTPS on port 443, with ports 80 and 8080 answering /health and redirecting everything else to HTTPS. A fourth listener, port 8081, is not published: identity calls it on the Compose network to drop revoked tokens from the gateway's authorization cache. These are the prefixes it routes, taken from open-security-gateway/nginx/conf.d/wildbox_gateway.conf.

Gateway path	Service	Authentication
/health	gateway	none
/auth/jwt/login, /auth/jwt/…	identity /api/v1/auth/jwt/…	none for the login, rate-limited per client address; POST /auth/jwt/logout takes the bearer token and revokes it
/auth/register	identity /api/v1/auth/register	none, rate-limited per client address
/auth/forgot-password	identity /api/v1/auth/forgot-password	none, rate-limited per client address
/auth/reset-password	identity /api/v1/auth/reset-password	none; takes the reset token
/auth/users/…	identity /api/v1/users/… (for example /auth/users/me)	validated by identity
POST /auth/logout	identity /api/v1/auth/logout	bearer token, revoked on success (a GET serves the dashboard's logout page)
/api/v1/identity/auth/…	identity /api/v1/auth/…	validated by identity
/api/v1/identity/…	identity /api/v1/… (/api/v1/identity/health: identity /health)	validated by identity; /api/v1/identity/health is authenticated by the gateway
/api/v1/tools, /api/v1/tools/…	tools API /api/tools/…	required
/api/v1/tasks, /api/v1/tasks/…	tools API /api/tasks/… (asynchronous tool runs)	required
/api/v1/data/…	data /api/v1/… (/api/v1/data/health: data /health)	required
/api/v1/guardian/…	guardian /api/v1/…	required
/api/v1/responder/…	responder /v1/…	required
/api/v1/agents/…	agents /v1/… (/api/v1/agents/stats: agents /stats)	required
/api/v1/cspm/…	cspm /api/v1/…	required
/	dashboard	handled by the dashboard

The sensor service is not routed through the gateway in this release, and neither is n8n, the optional automations service: its editor is on port 5678 of the host's loopback interface. Any other path under /api/ returns 404, including /api/tools/…, the old alias of /api/v1/tools/, which was removed. /tools/, where the tools service's standalone web UI used to be, also returns 404: run tools from the dashboard's toolbox or through /api/v1/tools/. For the ports each service listens on locally, see the service ports reference.