API Reference
How to authenticate, where each service's API lives behind the gateway, and where its endpoints are documented.
The endpoint references are written by hand from the code. Where one disagrees with a running service, the service is right: please open an issue.
Authentication
Every API is reached through the gateway over HTTPS. Log in with a form-encoded POST /auth/jwt/login (fields username, the email address, and password); the response carries access_token. Send it as Authorization: Bearer <token>. The gateway also accepts an API key in X-API-Key.
TOKEN=$(curl -s --cacert open-security-gateway/ssl/wildbox.crt \
-X POST https://localhost/auth/jwt/login \
--data-urlencode "username=$ADMIN_EMAIL" \
--data-urlencode "password=$ADMIN_PASSWORD" | jq -r .access_token)
curl -s --cacert open-security-gateway/ssl/wildbox.crt \
-H "Authorization: Bearer $TOKEN" https://localhost/api/v1/identity/users/me- Tokens are HS256 JWTs valid for 30 minutes. There is no refresh endpoint: log in again.
POST /auth/logoutorPOST /auth/jwt/logoutwith the bearer token revokes it, at identity and in the gateway's authorization cache.- After 5 failed logins for the same email, login answers 429 with
Retry-After: 900for 15 minutes, even with the right password. - Wrong credentials answer 400.
Details: Authentication and sessions. The complete, tested sequence: Quick start.
Services
Gateway path prefixes and the endpoint reference for each service. The full routing table, including the paths that need no authentication, is under Gateway routes.
| Service | Gateway path | Reference |
|---|---|---|
| Identity: users, login, API keys, teams | /auth/jwt/…, /api/v1/identity/… | Identity endpoints |
| Tools: 52 security tools | /api/v1/tools/…, /api/v1/tasks/… (asynchronous runs) | Tools endpoints |
| Data: threat intelligence and IOCs | /api/v1/data/… | Data endpoints |
| Guardian: assets, vulnerabilities, remediation | /api/v1/guardian/… | Guardian endpoints |
| Responder: incident-response playbooks | /api/v1/responder/… | Responder endpoints |
| Agents: AI-assisted analysis | /api/v1/agents/… | Agents endpoints |
CSPM: 22 configuration checks against live AWS accounts; other providers are refused with 400, and GET /api/v1/cspm/providers lists the ones that can be scanned | /api/v1/cspm/… | CSPM endpoints |
Backends also listen on 127.0.0.1 ports of the Docker host, for health checks and debugging; see Service ports. identity, agents, responder, data and cspm serve their own interactive documentation and /openapi.json there only when ENVIRONMENT is development; tools serves no documentation pages, and its /openapi.json under the same condition.
Errors
identity, tools, data, responder, cspm and agents answer every error in one shape; request_id matches the X-Request-ID the gateway sets, so a failure can be found in the logs:
{
"error": {
"code": 404,
"message": "Not Found",
"type": "HTTPException",
"request_id": "<id>"
}
}error.code is the HTTP status and error.message is always a sentence. error.details is present when the error carries data: the list of field errors of a 422, or the dict or list a service raised. A machine-readable code that a service raises, such as REGISTER_INVALID_PASSWORD from identity, is at error.details.code.
guardian is a Django REST Framework service and uses that framework's error format.