API Key Authentication

🔐 API Key Authentication

ActiveCampaign uses API key authentication with account-specific base URLs. Each account has a unique API URL and API key that must be obtained from the ActiveCampaign dashboard.

🌐 Environment Variables

Variable	Description	Example
`ACTIVECAMPAIGN_API_VERSION`	API version path	`/api/3`

📋 API Endpoints

Method	Endpoint	Description	Auth Required
POST	`/v1/integrations/activecampaign/auth`	Save API credentials	✅ JWT
DELETE	`/v1/integrations/activecampaign/auth`	Delete stored credentials	✅ JWT

🔄 Authentication Flow

Step 1: Obtain API Credentials

From ActiveCampaign dashboard:

Login to your ActiveCampaign account
Navigate to Settings → Developer
Copy API URL - Example: https://dashclicks83379.api-us1.com
Copy API Key - Example: a0b219e049fb4f027fd927ade6a21d38abc123def456789

Step 2: Save Credentials

Endpoint: POST /auth

Request Body:

api_key (required) - ActiveCampaign API key
base_url (required) - Account-specific API base URL

Request:

POST /v1/integrations/activecampaign/auth
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "api_key": "a0b219e049fb4f027fd927ade6a21d38abc123def456789",
  "base_url": "https://dashclicks83379.api-us1.com"
}

Process:

Check for existing credentials (one per user/account)
Validate base_url is provided
Validate api_key is provided
Test API key by making request to /api/3/contacts
If valid, save credentials to MongoDB
If invalid, return error

Success Response:

{
  "success": true,
  "message": "SUCCESS"
}

Error Responses:

// Credentials already exist
{
  "success": false,
  "errno": 400,
  "message": "Record already exist!"
}

// Missing base URL
{
  "success": false,
  "errno": 400,
  "message": "Base URL is required!"
}

// Missing API key
{
  "success": false,
  "errno": 400,
  "message": "API Key is required!"
}

// Invalid credentials
{
  "success": false,
  "errno": 400,
  "message": "Invalid base_url or api_key."
}

Step 3: Delete Credentials

Endpoint: DELETE /auth

Request:

DELETE /v1/integrations/activecampaign/auth
Authorization: Bearer {jwt_token}

Success Response:

{
  "success": true,
  "message": "SUCCESS"
}

Error Response:

{
  "success": false,
  "errno": 400,
  "message": "Unauthorised Access."
}

🔑 Credential Storage

MongoDB Document Structure

{
  _id: ObjectId("..."),
  api_key: "a0b219e049fb4f027fd927ade6a21d38abc123def456789",
  base_url: "https://dashclicks83379.api-us1.com",
  account_id: "12345",
  owner: "user_Lwh9EzeD8",
  workspace_id: "1234567890"
}

Model Methods

find(account_id, owner)

keysModel.find(account_id, owner).then(result => {
  // Returns credential document or null
});

save(req)

keysModel.save(req).then(result => {
  // Saves credentials from request
});

delete(account_id, owner)

keysModel.delete(account_id, owner).then(result => {
  // Deletes credentials
});

🌍 Base URL Structure

Each ActiveCampaign account has a unique base URL based on:

Account Name/ID: Unique identifier
Region: Geographic location

Format:

https://{account_identifier}.api-{region}.com

Common Regions:

us1 - United States (primary)
eu1 - European Union
ap1 - Asia Pacific

Examples:

https://dashclicks83379.api-us1.com
https://mycompany123.api-us1.com
https://acmecorp.api-eu1.com

🔒 API Key Validation

When credentials are saved, the integration validates them by making a test request:

Validation Request:

GET {base_url}/api/3/contacts?limit=1
Api-Token: {api_key}

Valid Response: 200 OK with contact data

Invalid Response: 401 Unauthorized or 403 Forbidden

This ensures:

API key is active
Base URL is correct
Account has necessary permissions

🎯 Authorization Middleware

All protected endpoints require JWT authentication:

JWT Token Structure:

req.auth = {
  account_id: '12345', // DashClicks account ID
  uid: 'user_Lwh9EzeD8', // DashClicks user ID
  workspace_id: '1234567890', // DashClicks workspace ID
  // ... other JWT claims
};

Required JWT Claims

Claim	Description	Example
`account_id`	DashClicks account ID	`"12345"`
`uid`	DashClicks user ID	`"user_Lwh9EzeD8"`
`workspace_id`	DashClicks workspace ID	`"1234567890"`

🔐 Security Features

Single Connection Per User

Only one set of credentials allowed per user/account combination:

Prevents credential duplication
Ensures data consistency
Simplifies management

To update credentials:

Delete existing credentials
Save new credentials

Credential Validation

All credentials validated before storage:

API Key Format: Checked for validity
Base URL Format: Validated as HTTPS URL
API Access: Test request confirms connectivity

Storage Security

Credentials stored in MongoDB
Should be encrypted at rest (deployment-specific)
Access controlled by DashClicks authentication

⚠️ Error Handling

Error	Cause	Solution
"Record already exist!"	Credentials already saved	Delete old credentials first
"Base URL is required!"	Missing `base_url` parameter	Provide base URL from ActiveCampaign
"API Key is required!"	Missing `api_key` parameter	Provide API key from ActiveCampaign
"Invalid base_url or api_key."	Credentials don't work	Verify credentials in ActiveCampaign dashboard
"Unauthorised Access."	No credentials found	Save credentials first

📝 Important Notes

🔑 No Expiration: API keys don't expire automatically
🌍 Region-Specific: Base URL must match account region
👤 One Connection: Single credential set per user/account
✅ Validation: Credentials tested before storage
🔒 Security: Store credentials securely
⚡ No Refresh: No token refresh needed (unlike OAuth)

🔗 API Request Format

After saving credentials, all API requests use:

Headers:

Api-Token: {api_key}
Content-Type: application/json

URL Format:

{base_url}/api/3/{endpoint}

Example:

GET https://dashclicks83379.api-us1.com/api/3/contacts
Api-Token: a0b219e049fb4f027fd927ade6a21d38abc123def456789

API Key Authentication