ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Python active-directorycloud-securitydefensive-validationfastapigood-first-issuemitre-attackopsecreactred-teamreportingsecurity
docs: align API key response contract
Mafifrizi4a08fe3e1623
diff --git a/docs/api-reference.md b/docs/api-reference.mdindex c80a503..b5c5cef 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -1,8 +1,10 @@# ARES API Reference> **Base URL:** `http://localhost:8080`-> All endpoints require `Authorization: Bearer <token>` or `X-API-Key: <key>`-> **except** `POST /auth/token` and `GET /health`.+> API endpoints require authentication unless noted otherwise. Automation+> endpoints may accept `X-API-Key`; account/security management endpoints use+> JWT/browser sessions only. `POST /auth/token` and `GET /health` are+> unauthenticated.>> **Note:** The web dashboard (`/dashboard/*`) has its own authentication> using the same tokens — see [Dashboard](#dashboard) section.@@ -119,35 +121,54 @@ Change password for the authenticated user.Create an API key for the authenticated user.-API keys are generated inside ARES after a user has authenticated. They are for-automation and integrations that call API endpoints with `X-API-Key`. They are-separate from deployment secrets such as `ARES_SECRET_KEY` and-`ARES_ENCRYPTION_KEY`, which must be generated by the deployer before startup.+API keys are generated inside ARES after a user has authenticated with a+JWT/browser session. Existing API keys cannot create, list, revoke, or manage+account credentials.++API keys are for automation and integrations that call API endpoints with+`X-API-Key`. They are separate from deployment secrets such as+`ARES_SECRET_KEY` and `ARES_ENCRYPTION_KEY`, which must be generated by the+deployer before startup.```json-{ "name": "CI pipeline key" }+{+ "name": "CI pipeline key",+ "scopes": "read",+ "expires_days": 90+}```+`scopes` may be `read`, `write`, or `admin`. API-key scopes are an additional+restriction on API-key-compatible routes and do not replace RBAC.+**Response:**```json-{ "key_id": "...", "raw_key": "ares_...", "name": "CI pipeline key" }+{+ "id": "...",+ "key": "ares_...",+ "note": "Save this key — it will NOT be shown again.",+ "prefix": "ares_..."+}```-> Store `raw_key` immediately — it is not recoverable after this response.+> Store `key` immediately — the full API key secret is not recoverable after+> this response.> In the dashboard, the same one-time secret is shown in the `Save your key`-> modal. The key list shows metadata and a prefix only.+> modal. The key list shows metadata and a prefix only, not the full secret.---### `GET /auth/api-keys`-List API keys for the authenticated user (key values are masked).+List API keys for the authenticated user with a JWT/browser session. The+response returns metadata and a key prefix only; it does not return the full+secret.---### `DELETE /auth/api-keys/{key_id}`-Revoke an API key.+Revoke an API key with a JWT/browser session.---