Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(auth): document allowedChats on API keys

Yudhi Armyndharis63485da2bbb7
diff --git a/docs/04-security-design.md b/docs/04-security-design.md
index f8934b3d9..353ec81a3 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -72,7 +72,7 @@ fixed `dev-admin-key`; with neither set, the seed key is generated in the format
### Permission Model
API keys carry **no permission strings**. Authorization is a role hierarchy on the key itself, plus
-two scoping dimensions enforced by `ApiKeyGuard`.
+three scoping dimensions enforced by `ApiKeyGuard`.
| Role | Rank | Meaning |
| ---------- | ---- | -------------------------------------------------------------------- |
@@ -83,10 +83,11 @@ two scoping dimensions enforced by `ApiKeyGuard`.
A route declares its minimum level with `@RequireRole(...)`; a key passes when its role ranks at or
above that level (`AuthService.hasPermission`). A key below it is rejected with `403 Forbidden`.
-| Scope | Field | Effect |
-| --------- | ----------------- | -------------------------------------------------------------------------------------------------------- |
-| Source IP | `allowedIps` | Empty/absent = unrestricted; non-empty = fail-closed IP whitelist (see §4.3) |
-| Sessions | `allowedSessions` | Empty/absent = every session; non-empty = a request carrying any other session id is rejected with `401` |
+| Scope | Field | Effect |
+| --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Source IP | `allowedIps` | Empty/absent = unrestricted; non-empty = fail-closed IP whitelist (see §4.3) |
+| Sessions | `allowedSessions` | Empty/absent = every session; non-empty = a request carrying any other session id is rejected with `401` |
+| Chats | `allowedChats` | Empty/absent = every chat; non-empty = default-deny: only chat-scoped routes, and only for a listed chat, else `403`; `/events`, MCP and Bull Board refuse the key |
The key-lifecycle routes (`/api/auth/api-keys`) are additionally fenced with `@RequireUnscopedKey()`:
a session-scoped key is refused there whatever its role, so it cannot mint or widen credentials
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index d17f05632..642dcc3bb 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -253,6 +253,7 @@ erDiagram
varchar role
simple_array allowedIps
simple_array allowedSessions
+ simple_array allowedChats
boolean isActive
timestamp expiresAt
timestamp lastUsedAt
@@ -542,6 +543,7 @@ CREATE TABLE api_keys (
role VARCHAR(20) NOT NULL DEFAULT 'operator', -- admin | operator | viewer
"allowedIps" TEXT, -- simple-array (comma-joined), null = any IP
"allowedSessions" TEXT, -- simple-array, null = all sessions
+ "allowedChats" TEXT, -- simple-array, null = all chats
"isActive" BOOLEAN NOT NULL DEFAULT 1,
"expiresAt" DATETIME,
"lastUsedAt" DATETIME,
@@ -554,7 +556,7 @@ CREATE UNIQUE INDEX "IDX_df3b25181df0b4b59bd93f16e1" ON api_keys("keyHash");
```
> [!NOTE]
-> Access control is **role-based** (`admin` / `operator` / `viewer`), optionally scoped by `allowedIps` and `allowedSessions`. There is no granular `permissions` string array — see [04 - Security Design](./04-security-design.md) for what each role can do.
+> Access control is **role-based** (`admin` / `operator` / `viewer`), optionally scoped by `allowedIps`, `allowedSessions` and `allowedChats`. There is no granular `permissions` string array — see [04 - Security Design](./04-security-design.md) for what each role can do.
---
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index e3efb7542..d96eb7720 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -47,6 +47,8 @@ API keys carry one of three roles, ordered by privilege:
A key may additionally be scoped to specific sessions (`allowedSessions`) and/or source IPs (`allowedIps`). The scope/IP check runs in the guard **before** any role check, so a request outside that scope is rejected with `401` (not `403`) even if the role would otherwise allow it.
+A key may also be restricted to selected chats (`allowedChats`: group `<id>@g.us`, contact `<phone>@c.us` or `<lid>@lid`, or a bare phone number, which is stored as `<phone>@c.us`). An empty or absent list leaves the key unrestricted. A chat-restricted key is **denied by default**: it may call only routes marked as chat-scoped, and every other route (webhooks, automation, status, channels, key management, and any route added later) answers `403 "API key is restricted to selected chats"` after the role check. On a chat-scoped route, every chat id the request names (a `:chatId` / `:groupId` / `:contactId` path param, `?chatId=`, a body `chatId` / `fromChatId` / `toChatId`, and each `messages[].chatId` of a bulk send) must be inside the allowlist, or the request answers `403 "API key not authorized for this chat"`; a contact entry also matches its mapped `@lid` form, and the reverse. Chat list routes return only the allowed chats. A `quotedMessageId` is refused with `403` everywhere except the reply route, which binds the quote to the chat it sends into. The surfaces outside the REST guard refuse a chat-restricted key outright: the `/events` WebSocket at the handshake and on every subscribe, every MCP tool call (`403`), and the Bull Board queue dashboard (`403`).
+
### API-Key Lifecycle
OpenWA seeds an initial admin key on first run (printed to the startup log and written to `data/.api-key`, or `/app/data/.api-key` in Docker). Use it to mint scoped, lower-privilege keys for integrations. Full key creation, listing, rotation, and revocation are documented under the auth resource in **§6.4.9 (API Keys)**.
@@ -4813,13 +4815,14 @@ Create a new API key; returns the full plaintext key exactly once.
**Request body** — `CreateApiKeyDto`
-| Field | Type | Required | Constraints | Description |
-| ----------------- | -------------------------------------- | -------- | ----------------------------------------------------------------------- | ------------------------------------ |
-| `name` | string | yes | length 3–100 | Friendly name for the key. |
-| `role` | enum `admin` \| `operator` \| `viewer` | no | `@IsEnum` | Defaults to `operator` when omitted. |
-| `allowedIps` | string[] | no | each entry a valid **IPv4** address or IPv4 CIDR `/0-32`; IPv6 rejected | IP whitelist (IPv4-only by design). |
-| `allowedSessions` | string[] | no | each `@IsString` | Session IDs this key may access. |
-| `expiresAt` | string (ISO 8601 date) | no | `@IsDateString` | Stored as a `Date`. |
+| Field | Type | Required | Constraints | Description |
+| ----------------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `name` | string | yes | length 3–100 | Friendly name for the key. |
+| `role` | enum `admin` \| `operator` \| `viewer` | no | `@IsEnum` | Defaults to `operator` when omitted. |
+| `allowedIps` | string[] | no | each entry a valid **IPv4** address or IPv4 CIDR `/0-32`; IPv6 rejected | IP whitelist (IPv4-only by design). |
+| `allowedSessions` | string[] | no | each `@IsString` | Session IDs this key may access. |
+| `allowedChats` | string[] | no | unique entries, each a group `<id>@g.us`, a contact `<phone>@c.us` / `<lid>@lid`, or a bare phone number | Chat IDs this key may reach (see [Roles & Authorization](#roles--authorization)). |
+| `expiresAt` | string (ISO 8601 date) | no | `@IsDateString` | Stored as a `Date`. |
```json
{
@@ -4867,13 +4870,14 @@ Update mutable fields of an API key. `isActive` is **not** updatable here — us
**Request body** — `UpdateApiKeyDto`
-| Field | Type | Required | Constraints | Description |
-| ----------------- | -------------------------------------- | -------- | ------------------------ | --------------------------------------------------------- |
-| `name` | string | no | length 3–100 | Applied only if truthy. |
-| `role` | enum `admin` \| `operator` \| `viewer` | no | `@IsEnum` | Applied only if truthy. |
-| `allowedIps` | string[] | no | IPv4 address / CIDR only | Applied if not `undefined` (can be set to `[]` to clear). |
-| `allowedSessions` | string[] | no | each `@IsString` | Applied if not `undefined`. |
-| `expiresAt` | string (ISO 8601 date) | no | `@IsDateString` | Applied if not `undefined`; empty/falsy clears to `null`. |
+| Field | Type | Required | Constraints | Description |
+| ----------------- | -------------------------------------- | -------- | ------------------------ | ------------------------------------------------------------------------- |
+| `name` | string | no | length 3–100 | Applied only if truthy. |
+| `role` | enum `admin` \| `operator` \| `viewer` | no | `@IsEnum` | Applied only if truthy. |
+| `allowedIps` | string[] | no | IPv4 address / CIDR only | Applied if not `undefined` (can be set to `[]` to clear). |
+| `allowedSessions` | string[] | no | each `@IsString` | Applied if not `undefined`. |
+| `allowedChats` | string[] | no | same as create | Applied if not `undefined` (`[]` clears it, making the key unrestricted). |
+| `expiresAt` | string (ISO 8601 date) | no | `@IsDateString` | Applied if not `undefined`; empty/falsy clears to `null`. |
```json
{