Authentication & API Keys

🔐 Authentication & Configuration

Authentication Method: API Key (Master + Subuser API Keys)

Required Environment Variables:

Variable	Description	Required
SENDGRID_API_KEY	Master Sendgrid API key	✅
SENDGRID_DEFAULT_DOMAIN_ID	Default domain ID for subusers	✅
SENDGRID_EVENT_WEBHOOK_URL	Webhook URL for email events	✅
SENDGRID_INBOUND_WEBHOOK_URL	Webhook URL for inbound emails	✅
CONVERSATION_SOCKET	Conversation socket service URL	✅
APP_SECRET	JWT secret for socket authentication	✅

Example Configuration:

SENDGRID_API_KEY=SG.abc123...
SENDGRID_DEFAULT_DOMAIN_ID=12345678
SENDGRID_EVENT_WEBHOOK_URL=https://api.dashclicks.com/v1/integrations/sendgrid/webhook
SENDGRID_INBOUND_WEBHOOK_URL=https://api.dashclicks.com/v1/integrations/sendgrid/webhook/inbound
CONVERSATION_SOCKET=http://localhost:6001
APP_SECRET=your_jwt_secret

Credential Storage: Master API key in environment, subuser API keys in integrations-sendgrid-keys collection

🔑 API Key Management

Get API Key

Endpoint: GET /v1/integrations/sendgrid/api-key

Purpose: Retrieve existing Sendgrid API key for an account

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "account_id": "507f191e810c19729de860ea",
    "api_key": "SG.xyz123..."
  }
}

Add API Key

Endpoint: POST /v1/integrations/sendgrid/api-key

Purpose: Generate new Sendgrid API key for a subuser

Process:

1. Get subuser from integrations-sendgrid-subusers

2. Check if API key already exists (return 403 if exists)

3. Create API key via Sendgrid API:

   POST https://api.sendgrid.com/v3/api_keys
   Authorization: Bearer {SENDGRID_API_KEY}
   On-Behalf-Of: {subuser_username}
   
   {
     "name": "Dashboard Access"
   }

4. Store in integrations-sendgrid-keys collection

5. Create webhook for subuser via WebHookModel.createWebhook()

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "account_id": "507f191e810c19729de860ea",
    "api_key": "SG.xyz123..."
  }
}

Error Scenarios:

// API key already exists
{
  "success": false,
  "errno": 403,
  "message": "Sendgrid Api Key already exist"
}

// No subuser found
{
  "success": false,
  "errno": 403,
  "message": "No subuser associated with this account"
}
```## 🛡️ Middleware

### getSendgridApiKey

**Purpose**: Validate and attach Sendgrid API key to request

**Location**: `Middleware/getSendgridApiKey.js`

**Usage**:

```javascript
router.post('/mail', verifyAuthorization(), getSendgridApiKey, (req, res) => {
  // req.sendgrid_api_key available here
});

Logic:

1. Extract account_id from req.auth
2. Query SendgridCollection.getApiKey({ account_id })
3. If not found:

   {
     "success": false,
     "errno": 403,
     "message": "Sendgrid api key is misconfigured.",
     "error": "SENDGRID_API_MISCONFIGURED"
   }

4. If found: Attach req.sendgrid_api_key
5. Call next()

Implementation:

const getSendgridApiKey = async (req, res, next) => {
  try {
    const { account_id } = req.auth;

    const { isEmpty, doc } = await SendgridCollection.getApiKey({ account_id });

    if (isEmpty) {
      throw {
        message: 'Sendgrid api key is misconfigured.',
        error: 'SENDGRID_API_MISCONFIGURED',
        errno: 403,
      };
    }

    req.sendgrid_api_key = doc.api_key;
    next();
  } catch (error) {
    res.status(error.errno || 500).json({
      success: false,
      errno: error.errno || 500,
      message: error.message,
      error: error.error,
    });
  }
};

📦 SendgridCollection Model

Purpose: API key management in database

Methods:

getApiKey() Method

SendgridCollection.getApiKey({ account_id });
// Returns: { isEmpty: boolean, doc: { id, account_id, api_key } }

Query:

db.getCollection('integrations.sendgrid.keys').findOne({
  account_id: ObjectId(account_id),
});

addApiKey() Method

SendgridCollection.addApiKey({
  account_id,
  api_key,
});
// Returns: { id, account_id, api_key }

Creates Document:

{
  _id: new ObjectId(),
  account_id: ObjectId(account_id),
  api_key: "SG.xyz123..."
}

🎛️ ApiKeyControllerLocation: Controllers/ApiKeyController.js

getApiKey() Controller

Route: GET /v1/integrations/sendgrid/auth

Logic:

1. Extract account_id from req.auth
2. Call SendgridCollection.getApiKey({ account_id })
3. Return API key document

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "account_id": "507f191e810c19729de860ea",
    "api_key": "SG.abc123..."
  }
}

Error:

{
  "success": false,
  "errno": 400,
  "message": "Record Not found"
}

addApiKey()

Route: POST /v1/integrations/sendgrid/auth

Logic:

1. Get subuser from account document

2. Check if API key already exists:

   const existingKey = await SendgridCollection.getApiKey({ account_id });
   if (!existingKey.isEmpty) {
     throw { message: 'Sendgrid Api Key already exist', errno: 403 };
   }

3. Create API key via Sendgrid API (on-behalf-of subuser):

   const response = await this.client.request({
     method: 'POST',
     url: '/v3/api_keys',
     body: {
       name: 'Dashboard Access',
     },
     headers: {
       'on-behalf-of': subuser.username,
     },
   });

4. Store in database:

   const apiKey = await SendgridCollection.addApiKey({
     account_id: account_id,
     api_key: response.body.api_key,
   });

5. Create webhook:

   await WebHookModel.createWebhook({
     account_id,
     api_key: response.body.api_key,
   });

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "account_id": "507f191e810c19729de860ea",
    "api_key": "SG.xyz123..."
  }
}

🔗 Related Routes

Route Configuration (Routes/apikey.js):

const router = require('express').Router();
const ApiKeyController = require('../Controllers/ApiKeyController');
const { verifyAuthorization } = require('../../../Middleware/verifyAuthorization');

router.get('/', verifyAuthorization(), ApiKeyController.getApiKey);
router.post('/', verifyAuthorization(), ApiKeyController.addApiKey);

module.exports = router;

Mounted in index.js:

app.use('/auth', require('./Routes/apikey'));

🚨 Error Handling

Common Error Scenarios:

Error	Scenario	HTTP Status	Handling
403	No API key found	403	User must create API key first
403	API key already exists	403	Return error message
403	No subuser associated	403	Must create subuser first
403	API key misconfigured	403	Middleware blocks request
500	Sendgrid API call failed	500	Return Sendgrid error message
400	Invalid account_id in token	400	JWT verification failed

🧪 Testing

Test API Key Retrieval

curl -X GET http://localhost:5003/v1/e/sendgrid/auth \
  -H "Authorization: Bearer {jwt_token}"

Expected Response (if exists):

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "account_id": "507f191e810c19729de860ea",
    "api_key": "SG.xyz123..."
  }
}

Test API Key Creation

curl -X POST http://localhost:5003/v1/e/sendgrid/auth \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json"

Expected Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "account_id": "507f191e810c19729de860ea",
    "api_key": "SG.xyz123..."
  }
}

Test Middleware

// Test that middleware blocks requests without API key
const account = await Account.create({
  sendgrid: {
    subuser: { username: 'test_subuser' },
  },
});

// No API key in database
const response = await request(app)
  .post('/v1/e/sendgrid/mail')
  .set('Authorization', `Bearer ${jwtToken}`)
  .send({ subject: 'Test' });

expect(response.status).toBe(403);
expect(response.body.error).toBe('SENDGRID_API_MISCONFIGURED');

⚠️ Important Notes

• 🔑 Master vs Subuser Keys: Master key in environment only, subuser keys in database
• 🛡️ Middleware Protection: All email-sending routes protected by getSendgridApiKey
• 🚫 Duplicate Prevention: Checks for existing API key before creating new one
• 🔗 Webhook Auto-Setup: Creating API key automatically configures event webhook
• 📊 One Key Per Account: Each DashClicks account gets exactly one Sendgrid API key
• 🔄 Key Rotation: No automatic rotation - must delete and recreate manually
• 👥 Subuser Requirement: Cannot create API key without existing subuser
• 📝 Name Convention: All API keys created with name "Dashboard Access"

🔗 Related Documentation

• Sendgrid API Keys Documentation
• On-Behalf-Of Header
• Subuser Management
• Webhook Configuration