Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

feat(auth): report the running engine from POST /auth/validate

Yudhi Armyndharisde2d4a0332d9
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index d1b3aac46..eab0d88db 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -4968,16 +4968,16 @@ Permanently delete an API key (hard delete). Also drops any un-flushed usage acc
#### POST /api/auth/validate
-Validate the supplied `X-API-Key` and report its validity and role.
+Validate the supplied `X-API-Key` and report its validity, its role, and the engine the gateway runs.
**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. On success it returns the caller's role. 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. 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.
**Response** `200`
```json
-{ "valid": true, "role": "operator" }
+{ "valid": true, "role": "operator", "engineType": "whatsapp-web.js" }
```
**Errors:** `401` missing/invalid/revoked/expired key (raised by the global guard before the handler); `403` a key restricted with `allowedChats`
@@ -5352,7 +5352,7 @@ omitted per engine.
#### GET /api/infra/engines/current
-Get the currently active engine type.
+Get the currently active engine type. A non-admin key reads the same value from `POST /api/auth/validate`.
**Auth:** API key (ADMIN)
diff --git a/docs/07-api-collection.md b/docs/07-api-collection.md
index 3513c34bb..6f3feddcd 100644
--- a/docs/07-api-collection.md
+++ b/docs/07-api-collection.md
@@ -1278,7 +1278,7 @@ curl -X DELETE "$BASE/api/auth/api-keys/3f2a1c9e-1b2d-4a5f-9c8e-aa11bb22cc33" \
#### POST /api/auth/validate
-Validate the supplied key and report its role (empty body; key read from the header).
+Validate the supplied key and report its role and the running engine (`engineType`); empty body, key read from the header.
```bash
curl -X POST "$BASE/api/auth/validate" \
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.md
index 1487dbf0d..afb9dc27e 100644
--- a/docs/18-sdk-design.md
+++ b/docs/18-sdk-design.md
@@ -119,10 +119,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 (`{ valid, role? }`). |
-| `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? }`). |
+| `request` | `client.request<T>(options)` | Raw escape hatch — issue an arbitrary request against the API. |
#### `sessions`
diff --git a/openapi.json b/openapi.json
index e5106dca9..2851ea1e9 100644
--- a/openapi.json
+++ b/openapi.json
@@ -10309,6 +10309,11 @@
"viewer"
],
"description": "The key's role; present only when valid."
+ },
+ "engineType": {
+ "type": "string",
+ "description": "Engine the process resolved at boot; present only when valid.",
+ "example": "baileys"
}
},
"required": [
diff --git a/sdk/go/types_misc.go b/sdk/go/types_misc.go
index bc2953422..17e558211 100644
--- a/sdk/go/types_misc.go
+++ b/sdk/go/types_misc.go
@@ -26,8 +26,9 @@ type HealthReadyResponse struct {
// AuthValidateResponse reports whether the API key is valid and its role.
type AuthValidateResponse struct {
- Valid bool `json:"valid"`
- Role string `json:"role,omitempty"`
+ Valid bool `json:"valid"`
+ Role string `json:"role,omitempty"`
+ EngineType string `json:"engineType,omitempty"`
}
// ── Template ───────────────────────────────────────────
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/AuthValidateResponse.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/AuthValidateResponse.java
index 8967584df..bd7041d9c 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/AuthValidateResponse.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/AuthValidateResponse.java
@@ -1,4 +1,4 @@
package com.rmyndharis.openwa.model;
/** Result of validating the configured API key. */
-public record AuthValidateResponse(boolean valid, String role) {}
+public record AuthValidateResponse(boolean valid, String role, String engineType) {}
diff --git a/sdk/javascript/src/types.ts b/sdk/javascript/src/types.ts
index bfd8107b1..b051e6df9 100644
--- a/sdk/javascript/src/types.ts
+++ b/sdk/javascript/src/types.ts
@@ -1189,6 +1189,7 @@ export interface HealthReadyResponse {
export interface AuthValidateResponse {
valid: boolean;
role?: string;
+ engineType?: string;
}
// ── Template ──────────────────────────────────────────────────────
diff --git a/sdk/python/openwa/types.py b/sdk/python/openwa/types.py
index 7a546f24e..ff6bdd35f 100644
--- a/sdk/python/openwa/types.py
+++ b/sdk/python/openwa/types.py
@@ -1204,6 +1204,7 @@ class HealthReadyResponse(TypedDict, total=False):
class AuthValidateResponse(TypedDict, total=False):
valid: bool
role: str
+ engineType: str
# ── Template ──────────────────────────────────────────────────────
diff --git a/src/modules/auth/auth-validate.controller.spec.ts b/src/modules/auth/auth-validate.controller.spec.ts
index f0e8b7d3e..87744f78f 100644
--- a/src/modules/auth/auth-validate.controller.spec.ts
+++ b/src/modules/auth/auth-validate.controller.spec.ts
@@ -1,25 +1,33 @@
import { AuthValidateController } from './auth-validate.controller';
import { ApiKey, ApiKeyRole } from './entities/api-key.entity';
+import { EngineFactory } from '../../engine/engine.factory';
describe('AuthValidateController', () => {
- const controller = new AuthValidateController();
+ const engineFactory = { getCurrentEngine: () => 'baileys' } as unknown as EngineFactory;
+ const controller = new AuthValidateController(engineFactory);
const makeKey = (over: Partial<ApiKey> = {}): ApiKey =>
({ id: 'k1', role: ApiKeyRole.OPERATOR, isActive: true, allowedIps: null, ...over }) as ApiKey;
- it('reports the guard-validated key as valid, echoing its role', () => {
+ it('reports the guard-validated key as valid, echoing its role and the running engine', () => {
expect(controller.validate(makeKey({ role: ApiKeyRole.ADMIN }))).toEqual({
valid: true,
role: ApiKeyRole.ADMIN,
+ engineType: 'baileys',
});
});
+ it('reports the engine to an operator key, which cannot read the admin-only infra route', () => {
+ // The dashboard needs the engine to gate status compose and the Channels tab for every writer.
+ expect(controller.validate(makeKey({ role: ApiKeyRole.OPERATOR }))).toMatchObject({ engineType: 'baileys' });
+ });
+
it('returns valid:true for an IP-restricted key (no IP-less re-validation false negative)', () => {
// The global guard already validated this key against the real client IP and attached it.
// The handler must NOT re-validate without an IP, which previously fail-closed and wrongly
// reported valid:false for any key carrying an allowedIps restriction.
const key = makeKey({ allowedIps: ['10.0.0.0/24'] });
- expect(controller.validate(key)).toEqual({ valid: true, role: key.role });
+ expect(controller.validate(key)).toEqual({ valid: true, role: key.role, engineType: 'baileys' });
});
it('returns valid:false when no key is attached (defense-in-depth)', () => {
diff --git a/src/modules/auth/auth-validate.controller.ts b/src/modules/auth/auth-validate.controller.ts
index a8cac2139..2d355236e 100644
--- a/src/modules/auth/auth-validate.controller.ts
+++ b/src/modules/auth/auth-validate.controller.ts
@@ -3,17 +3,20 @@ import { ApiTags, ApiOperation, ApiResponse, ApiHeader } from '@nestjs/swagger';
import { CurrentApiKey } from './decorators/auth.decorators';
import { ApiKey } from './entities/api-key.entity';
import { ValidateApiKeyResponseDto } from './dto';
+import { EngineFactory } from '../../engine/engine.factory';
@ApiTags('auth')
@Controller('auth')
export class AuthValidateController {
+ constructor(private readonly engineFactory: EngineFactory) {}
+
@Post('validate')
@HttpCode(HttpStatus.OK)
@ApiOperation({ summary: 'Validate an API key' })
@ApiHeader({ name: 'X-API-Key', description: 'API key to validate' })
@ApiResponse({ status: 200, description: 'API key is valid', type: ValidateApiKeyResponseDto })
@ApiResponse({ status: 401, description: 'Invalid or missing API key' })
- validate(@CurrentApiKey() apiKey?: ApiKey): { valid: boolean; role?: string } {
+ validate(@CurrentApiKey() apiKey?: ApiKey): { valid: boolean; role?: string; engineType?: string } {
// This route is behind the global API-key guard, so only a validated key reaches this handler
// (a missing/invalid key 401s first). The guard has already verified the key — including its
// client-IP and session-scope restrictions — and attached it to the request. Re-validating here
@@ -24,6 +27,8 @@ export class AuthValidateController {
if (!apiKey) {
return { valid: false };
}
- return { valid: true, role: apiKey.role };
+ // The engine rides along because GET /infra/engines/current is admin-only, and the dashboard needs
+ // it for every role that can post a status or read channels.
+ return { valid: true, role: apiKey.role, engineType: this.engineFactory.getCurrentEngine() };
}
}
diff --git a/src/modules/auth/dto/api-key.dto.ts b/src/modules/auth/dto/api-key.dto.ts
index a1d0cd44d..d2266fd0e 100644
--- a/src/modules/auth/dto/api-key.dto.ts
+++ b/src/modules/auth/dto/api-key.dto.ts
@@ -137,6 +137,12 @@ export class ValidateApiKeyResponseDto {
@ApiPropertyOptional({ enum: ApiKeyRole, description: "The key's role; present only when valid." })
role?: ApiKeyRole;
+
+ @ApiPropertyOptional({
+ description: 'Engine the process resolved at boot; present only when valid.',
+ example: 'baileys',
+ })
+ engineType?: string;
}
export class UpdateApiKeyDto {