feat: Allow API keys in request body (#6)

This change allows both the `X-MASTER-KEY` and `X-API-KEY` to be sent in the request body for POST requests, providing more flexibility for users.

The key extraction logic has been centralized into a new helper function to improve code maintainability.

The Swagger documentation, Postman collection, and README have all been updated to reflect these changes.

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>

Author: Codegres-com

README.md

@@ -168,15 +168,17 @@ All endpoints are prefixed with `/api`.
 
 ### **Authentication**
 
-This API uses a two-key system for security and session management:
+This API uses a two-key system for security and session management. Both keys can be provided in either the request header or the request body for `POST` requests, giving you more flexibility. For `GET` requests, they must be in the header.
 
 1.  **Master Key (`X-MASTER-KEY`)**:
-    -   This is a global key that grants access to the API server.
-    -   It must be included in the header of **every single request**.
+    -   This is a global key that grants access to the entire API server.
+    -   It can be included in the `X-MASTER-KEY` header or as a field in the JSON request body. The header will always take precedence if both are provided.
     -   This is the key you set in your `.env` file.
 
 2.  **Session Key (`X-API-KEY`)**:
     -   This key identifies a specific WhatsApp session (i.e., a specific phone number).
+    -   For `POST` requests, it can be in the `X-API-KEY` header or a field in the JSON/form-data body.
+    -   For `GET` requests, it must be in the `X-API-KEY` header.
     -   You can invent any unique string for each session (e.g., `user1_phone`, `work_account`, a random hash, etc.).
     -   The first time a new `X-API-KEY` is used with the `/connect` endpoint, a new session will be created for it.
 
@@ -266,12 +268,12 @@ Once connected, the server will save the session data in the `./sessions` folder
 #### 5. **Send Text Message (POST)**
 
 -   **Endpoint**: `POST /send-message`
--   **Headers**:
-    -   `X-MASTER-KEY: your_global_master_key_here`
-    -   `X-API-KEY: your_unique_session_key`
+-   **Headers**: `X-MASTER-KEY: your_global_master_key_here`
+-   **Description**: Sends a plain text message. The `X-API-KEY` can be in the header or, as shown below, in the request body.
 -   **Payload**: `application/json`
     ```json
     {
+      "X-API-KEY": "your_unique_session_key",
       "to": "+1234567890",
       "message": "Hello from the API!"
     }
@@ -281,24 +283,24 @@ Once connected, the server will save the session data in the `./sessions` folder
 
 -   **Endpoint**: `POST /send-attachment`
 -   **Description**: Sends an attachment to a specified number. This endpoint supports three methods: direct file upload, from a URL, or from a Base64 string.
--   **Headers**:
-    -   `X-MASTER-KEY: your_global_master_key_here`
-    -   `X-API-KEY: your_unique_session_key`
+-   **Headers**: `X-MASTER-KEY: your_global_master_key_here`
 
 ---
 
 ##### **Method 1: Direct File Upload**
 
 -   **Content-Type**: `multipart/form-data`
+-   **Description**: The `X-API-KEY` can be in the header or, as shown below, as a form field.
 -   **Body Fields**:
+    -   `X-API-KEY`: Your unique session key.
     -   `to`: The recipient's phone number.
     -   `file`: The file to be sent.
     -   `caption` (optional): A caption for the file.
 -   **Example `curl` Request**:
     ```bash
     curl -X POST http://localhost:3000/api/send-attachment \
     -H "X-MASTER-KEY: your_global_master_key_here" \
-    -H "X-API-KEY: your_unique_session_key" \
+    -F "X-API-KEY=your_unique_session_key" \
     -F "to=+1234567890" \
     -F "file=@/path/to/your/document.pdf" \
     -F "caption=Here is the document you requested."
@@ -309,9 +311,11 @@ Once connected, the server will save the session data in the `./sessions` folder
 ##### **Method 2: From URL or Base64**
 
 -   **Content-Type**: `application/json`
+-   **Description**: The `X-API-KEY` can be in the header or, as shown below, in the request body.
 -   **Payload**:
     ```json
     {
+      "X-API-KEY": "your_unique_session_key",
       "to": "+1234567890",
       "file": "url_or_base64_string",
       "type": "image/png", // Required only for Base64
@@ -326,8 +330,7 @@ Once connected, the server will save the session data in the `./sessions` folder
     curl -X POST http://localhost:3000/api/send-attachment \
     -H "Content-Type: application/json" \
     -H "X-MASTER-KEY: your_global_master_key_here" \
-    -H "X-API-KEY: your_unique_session_key" \
-    -d '{"to": "+1234567890", "file": "https://i.imgur.com/some-image.jpeg", "caption": "From a URL"}'
+    -d '{"X-API-KEY": "your_unique_session_key", "to": "+1234567890", "file": "https://i.imgur.com/some-image.jpeg", "caption": "From a URL"}'
     ```
 
 ---

src/controllers/authController.js

@@ -1,14 +1,6 @@
 const qrcode = require('qrcode');
 const { getStatus, initializeClient } = require('../services/sessionManager');
-
-/**
- * Extracts the session ID from the request headers.
- * @param {import('express').Request} req - The Express request object.
- * @returns {string|null} The session ID or null if not found.
- */
-const getSessionId = (req) => {
-    return req.get('X-API-KEY');
-};
+const { getSessionId } = require('../utils/apiKeyExtractor');
 
 /**
  * Handles the /connect endpoint.

src/controllers/messageController.js

@@ -1,13 +1,5 @@
 const { sendMessage, sendAttachment } = require('../services/sessionManager');
-
-/**
- * Extracts the session ID from the request headers.
- * @param {import('express').Request} req - The Express request object.
- * @returns {string|null} The session ID or null if not found.
- */
-const getSessionId = (req) => {
-    return req.get('X-API-KEY');
-};
+const { getSessionId } = require('../utils/apiKeyExtractor');
 
 /**
  * Handles the /send-message endpoint.

src/middleware/masterAuthMiddleware.js

@@ -4,9 +4,11 @@ const MASTER_API_KEY = process.env.MASTER_API_KEY;
 
 /**
  * Middleware to protect all API routes with a Master API key.
+ * The key can be provided in the 'X-MASTER-KEY' header or in the request body.
  */
 const masterApiKeyAuth = (req, res, next) => {
-    const masterKey = req.get('X-MASTER-KEY');
+    // Check for the key in the header first, then in the body.
+    const masterKey = req.get('X-MASTER-KEY') || (req.body ? req.body['X-MASTER-KEY'] : undefined);
 
     if (!MASTER_API_KEY) {
         // If the master key is not set in the environment, deny all requests.

src/routes/api.js

@@ -24,10 +24,19 @@ const upload = require('../middleware/uploadMiddleware');
  *   get:
  *     summary: Get QR code as a string
  *     tags: [Authentication]
- *     description: Establishes a new WhatsApp session and returns the QR code as a string for authentication.
+ *     description: Establishes a new WhatsApp session and returns the QR code as a string for authentication. Requires a session key.
+ *     parameters:
+ *       - in: header
+ *         name: X-API-KEY
+ *         schema:
+ *           type: string
+ *         required: true
+ *         description: Your unique session key.
  *     responses:
  *       200:
- *         description: QR code string.
+ *         description: QR code string or session status.
+ *       400:
+ *         description: Missing X-API-KEY header.
  *       500:
  *         description: Server error.
  */
@@ -39,7 +48,14 @@ router.get('/connect', getQrCodeString);
  *   get:
  *     summary: Get QR code as an image
  *     tags: [Authentication]
- *     description: Establishes a new WhatsApp session and returns the QR code as a PNG image.
+ *     description: Establishes a new WhatsApp session and returns the QR code as a PNG image. Requires a session key.
+ *     parameters:
+ *       - in: header
+ *         name: X-API-KEY
+ *         schema:
+ *           type: string
+ *         required: true
+ *         description: Your unique session key.
  *     responses:
  *       200:
  *         description: QR code image.
@@ -48,6 +64,10 @@ router.get('/connect', getQrCodeString);
  *             schema:
  *               type: string
  *               format: binary
+ *       400:
+ *         description: Missing X-API-KEY header.
+ *       404:
+ *         description: QR code not available.
  *       500:
  *         description: Server error.
  */
@@ -59,24 +79,38 @@ router.get('/connect/image', getQrCodeImage);
  *   post:
  *     summary: Send a text message
  *     tags: [Messaging]
- *     security:
- *       - ApiKeyAuth: []
+ *     description: Sends a text message from a specific session. The session is identified by the `X-API-KEY`, which can be passed either in the request header or in the request body. The header takes precedence.
+ *     parameters:
+ *       - in: header
+ *         name: X-API-KEY
+ *         schema:
+ *           type: string
+ *         required: false
+ *         description: Your unique session key (can be in header or body).
  *     requestBody:
  *       required: true
  *       content:
  *         application/json:
  *           schema:
  *             type: object
  *             properties:
- *               number:
+ *               X-API-KEY:
+ *                 type: string
+ *                 description: Your unique session key (if not provided in header).
+ *               to:
  *                 type: string
+ *                 description: The recipient's phone number.
  *               message:
  *                 type: string
+ *                 description: The text message to send.
+ *             required:
+ *               - to
+ *               - message
  *     responses:
  *       200:
  *         description: Message sent successfully.
  *       400:
- *         description: Bad request.
+ *         description: Bad request (e.g., missing parameters or session key).
  */
 router.post('/send-message', sendTextMessage);
 
@@ -86,27 +120,59 @@ router.post('/send-message', sendTextMessage);
  *   post:
  *     summary: Send a message with an attachment
  *     tags: [Messaging]
- *     security:
- *       - ApiKeyAuth: []
+ *     description: Sends a file attachment from a specific session. The session is identified by the `X-API-KEY`, which can be passed either in the request header or in the request body. The header takes precedence. This endpoint supports `multipart/form-data` for direct uploads and `application/json` for sending from a URL or Base64 string.
+ *     parameters:
+ *       - in: header
+ *         name: X-API-KEY
+ *         schema:
+ *           type: string
+ *         required: false
+ *         description: Your unique session key (can be in header or body).
  *     requestBody:
  *       required: true
  *       content:
  *         multipart/form-data:
  *           schema:
  *             type: object
  *             properties:
- *               number:
+ *               X-API-KEY:
+ *                 type: string
+ *                 description: Your unique session key (if not provided in header).
+ *               to:
  *                 type: string
  *               caption:
  *                 type: string
  *               file:
  *                 type: string
  *                 format: binary
+ *             required:
+ *                - to
+ *                - file
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               X-API-KEY:
+ *                 type: string
+ *                 description: Your unique session key (if not provided in header).
+ *               to:
+ *                 type: string
+ *               file:
+ *                 type: string
+ *                 description: A public URL to the file or a Base64 encoded string.
+ *               type:
+ *                 type: string
+ *                 description: The MIME type of the file (required for Base64).
+ *               caption:
+ *                 type: string
+ *             required:
+ *               - to
+ *               - file
  *     responses:
  *       200:
  *         description: Attachment sent successfully.
  *       400:
- *         description: Bad request.
+ *         description: Bad request (e.g., missing parameters or session key).
  */
 router.post('/send-attachment', upload.single('file'), sendAttachmentMessage);
 
@@ -116,8 +182,7 @@ router.post('/send-attachment', upload.single('file'), sendAttachmentMessage);
  *   post:
  *     summary: Upload a file
  *     tags: [File Upload]
- *     security:
- *       - ApiKeyAuth: []
+ *     description: Uploads a file to the server and returns a temporary URL. This endpoint does not require a session key (`X-API-KEY`).
  *     requestBody:
  *       required: true
  *       content:
@@ -142,9 +207,14 @@ router.post('/upload', upload.single('file'), uploadFile);
  *   get:
  *     summary: Send a message via GET request
  *     tags: [Messaging]
- *     security:
- *       - ApiKeyAuth: []
+ *     description: A simple GET request to send a text message or an attachment via URL. Requires a session key.
  *     parameters:
+ *       - in: header
+ *         name: X-API-KEY
+ *         schema:
+ *           type: string
+ *         required: true
+ *         description: Your unique session key.
  *       - in: query
  *         name: number
  *         schema:
@@ -155,13 +225,19 @@ router.post('/upload', upload.single('file'), uploadFile);
  *         name: message
  *         schema:
  *           type: string
- *         required: true
- *         description: The message content.
+ *         required: false
+ *         description: The text message to send (used as caption if `attachmentUrl` is present).
+ *       - in: query
+ *         name: attachmentUrl
+ *         schema:
+ *           type: string
+ *         required: false
+ *         description: A URL to a file to send as an attachment.
  *     responses:
  *       200:
  *         description: Message sent successfully.
  *       400:
- *         description: Bad request.
+ *         description: Bad request (e.g., missing parameters or session key).
  */
 router.get('/send', sendFromApi);
 

src/utils/apiKeyExtractor.js

@@ -0,0 +1,23 @@
+/**
+ * Extracts the session ID (API key) from the request.
+ * It checks the 'X-API-KEY' header first, then falls back to the request body.
+ *
+ * @param {import('express').Request} req - The Express request object.
+ * @returns {string|null} The session ID or null if not found.
+ */
+const getSessionId = (req) => {
+    const fromHeader = req.get('X-API-KEY');
+    if (fromHeader) {
+        return fromHeader;
+    }
+
+    if (req.body && req.body['X-API-KEY']) {
+        return req.body['X-API-KEY'];
+    }
+
+    return null;
+};
+
+module.exports = {
+    getSessionId,
+};