Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

docs: align API key response contract

Mafifrizi4a08fe3e1623
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 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.
---