Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(auth): document scoped in the key validation response

Yudhi Armyndharisb99e1340fa75
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index c05c0173c..b88f7e230 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -5042,12 +5042,12 @@ Validate the supplied `X-API-Key` and report its validity, its role, and the eng
**Auth:** API key (any valid role — VIEWER+)
-The key is read from the `X-API-Key` header, not the body; send an empty body. This route sits behind the global guard (it is not `@Public`), so a missing/invalid/revoked/expired key is rejected with `401` at the guard before the handler runs, and a key refused by its `allowedIps` with `403`. On success it returns the caller's role and `engineType`, the engine the process resolved at boot (`whatsapp-web.js` or `baileys`). The engine is reported to every role because `GET /api/infra/engines/current` is ADMIN-only. A key restricted with `allowedChats` is refused with `403 "API key is restricted to selected chats"`: the route is not open to a chat-scoped key.
+The key is read from the `X-API-Key` header, not the body; send an empty body. This route sits behind the global guard (it is not `@Public`), so a missing/invalid/revoked/expired key is rejected with `401` at the guard before the handler runs, and a key refused by its `allowedIps` with `403`. On success it returns the caller's role and `engineType`, the engine the process resolved at boot (`whatsapp-web.js` or `baileys`). The engine is reported to every role because `GET /api/infra/engines/current` is ADMIN-only. It also returns `scoped`, true when the key is restricted to selected sessions (a non-empty `allowedSessions`). A key restricted with `allowedChats` is refused with `403 "API key is restricted to selected chats"`: the route is not open to a chat-scoped key.
**Response** `200`
```json
-{ "valid": true, "role": "operator", "engineType": "whatsapp-web.js" }
+{ "valid": true, "role": "operator", "engineType": "whatsapp-web.js", "scoped": false }
```
**Errors:** `401` missing/invalid/revoked/expired key (raised by the global guard before the handler); `403` a key refused by its `allowedIps` (blocked or undeterminable client IP), or one restricted with `allowedChats`
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index 6077cc031..9ae7360be 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -124,10 +124,10 @@ All resources are accessed as properties on the client (`client.<resource>.<meth
The top-level client also exposes:
-| Method | Signature | Description |
-| --------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `auth` | `client.auth()` | Validate the configured API key and resolve its role and the running engine (`{ valid, role?, engineType? }`). |
-| `request` | `client.request<T>(options)` | Raw escape hatch — issue an arbitrary request against the API. |
+| Method | Signature | Description |
+| --------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `auth` | `client.auth()` | Validate the configured API key and resolve its role and the running engine (`{ valid, role?, engineType?, scoped? }`). |
+| `request` | `client.request<T>(options)` | Raw escape hatch — issue an arbitrary request against the API. |
#### `sessions`