ActiveCampaign API Authentication: Keys, Security, & Setup

Authentication overview

The ActiveCampaign API secures access through a simple API key mechanism. This method mandates that every request to the API includes a unique key and an account-specific API URL to verify the origin and authorization of the caller. This approach is standard for many RESTful APIs, providing a balance between ease of implementation and security for server-to-server communication or applications where the API key can be securely managed.

When interacting with the ActiveCampaign API, developers must supply two pieces of information with each request: an API URL and an API key. The API URL is unique to each ActiveCampaign account and directs requests to the correct instance, while the API key acts as a secret token, authenticating the user or application making the request. All communications with the ActiveCampaign API occur over HTTPS, ensuring that data transmitted, including the API key, is encrypted in transit using TLS (Transport Layer Security) protocols, helping to prevent eavesdropping and tampering. This is a fundamental security practice for web APIs, as detailed by the W3C Web Security FAQ.

This authentication model is suitable for integrations where the API key can be kept confidential, such as backend services, server-side applications, or desktop applications that do not expose the key directly to end-users. For client-side applications or mobile apps, additional security measures or alternative authentication flows (like OAuth, though not directly supported for direct API key access) might be necessary to prevent key exposure.

Supported authentication methods

The ActiveCampaign API primarily supports API key authentication. This method is straightforward and involves including specific credentials in your API requests.

API Key Authentication

API Key authentication requires two distinct pieces of information:

1. API URL: This is a unique URL specific to your ActiveCampaign account. It typically follows the format https://YOUR_ACCOUNT_NAME.activehosted.com/api/3. This URL directs your request to the correct ActiveCampaign instance.
2. API Key: A secret token that acts as your password for accessing the API. It must be kept confidential.

These credentials are included in the HTTP headers of your requests. Specifically, the API URL is used as the base for all API endpoints, and the API key is passed in the Api-Token header.

Getting your credentials

To obtain your ActiveCampaign API URL and API Key, you need to access your ActiveCampaign account settings. These credentials are generated within the platform and are unique to your account.

Steps to Retrieve Your API Credentials:

1. Log in to Your ActiveCampaign Account: Navigate to the ActiveCampaign login page and sign in with your username and password.
2. Access Settings: Once logged in, click on the "Settings" gear icon in the left-hand navigation menu.
3. Navigate to Developer Section: In the Settings menu, select "Developer."
4. Locate API Access: On the Developer page, you will find a section labeled "API Access." Here, your unique API URL and API Key will be displayed.
5. Copy Credentials: Carefully copy both the API URL and the API Key. It is crucial to treat your API Key as a sensitive password.
   

   For detailed, up-to-date instructions, always refer to the official ActiveCampaign developer documentation for API access.

Remember that these credentials grant access to your ActiveCampaign account data. Misuse or exposure of your API Key can lead to unauthorized access and potential data breaches. Always store and manage them securely.

Authenticated request example

Once you have your API URL and API Key, you can include them in your HTTP requests. The API Key is typically passed in a custom HTTP header, while the API URL forms the base of your endpoint.

Here's an example using curl to fetch a list of contacts, demonstrating how to include your API URL and API Token:

export AC_API_URL="https://YOUR_ACCOUNT_NAME.activehosted.com/api/3"
export AC_API_TOKEN="YOUR_API_KEY"

curl --request GET \
  --url "${AC_API_URL}/contacts" \
  --header "Api-Token: ${AC_API_TOKEN}" \
  --header "Accept: application/json"

In this example:

• YOUR_ACCOUNT_NAME.activehosted.com/api/3 should be replaced with your actual ActiveCampaign API URL.
• YOUR_API_KEY should be replaced with the API key generated from your ActiveCampaign account.
• The Api-Token header is where your API Key is passed.
• The Accept: application/json header indicates that you expect a JSON response.

Similar patterns apply across various programming languages. For instance, in Python, you might use the requests library:

import requests

AC_API_URL = "https://YOUR_ACCOUNT_NAME.activehosted.com/api/3"
AC_API_TOKEN = "YOUR_API_KEY"

headers = {
    "Api-Token": AC_API_TOKEN,
    "Accept": "application/json"
}

response = requests.get(f"{AC_API_URL}/contacts", headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

These examples illustrate the basic mechanism for authenticating requests. The ActiveCampaign API reference documentation provides further examples for specific endpoints and client libraries.

Security best practices

Securing your API keys and interactions with the ActiveCampaign API is important to protect your data and maintain compliance. Adhering to these best practices reduces the risk of unauthorized access and data breaches.

Keep API Keys Confidential

• Never embed keys directly in client-side code: API keys should not be exposed in public repositories, client-side JavaScript, mobile applications, or any environment where they can be easily extracted by end-users.
• Environment Variables: Store API keys as environment variables on your server or in secure configuration management systems. This prevents them from being hardcoded in your source code.
• Secret Management Services: Utilize secret management services (e.g., AWS Secrets Manager, Google Cloud Secret Manager, HashiCorp Vault) for production environments. These services provide secure storage, versioning, and access control for sensitive credentials.

Secure Transport and Communication

• Always use HTTPS: The ActiveCampaign API inherently requires HTTPS. Ensure your application always communicates over HTTPS to encrypt data in transit and prevent man-in-the-middle attacks. This is a baseline security measure for all web communication, as highlighted in Mozilla's explanation of HTTPS.
• Validate SSL/TLS Certificates: Ensure your HTTP client is configured to validate SSL/TLS certificates. This verifies that you are communicating with the legitimate ActiveCampaign API server and not an impostor.

Least Privilege Principle

• Limit API Key Scope: While ActiveCampaign API keys currently grant broad access, review developer documentation for any future updates that might allow for granular permissions. If multiple keys become available, use keys with the minimum necessary permissions for each application.
• Regular Audits: Periodically review which applications and services are using your API key and whether they still require access.

Key Rotation and Monitoring

• Rotate Keys: Implement a strategy for regularly rotating your API keys. This limits the window of exposure if a key is compromised.
• Monitor API Usage: Keep an eye on your ActiveCampaign account's API usage for any unusual activity. Unexpected spikes or patterns might indicate a compromised key.
• Revoke Compromised Keys: If you suspect an API key has been compromised, revoke it immediately through your ActiveCampaign account settings and generate a new one.

Error Handling and Logging

• Avoid Logging Sensitive Data: Ensure your application's logs do not inadvertently capture or store API keys or other sensitive authentication details.
• Secure Error Reporting: Configure error reporting to avoid exposing sensitive internal details, including API keys, in public error messages.