Let's build something great together

When you build integrations with ActiveCampaign, you can have a positive impact on small businesses across the world. This is where you can find ActiveCampaign API documentation, SDKs, support, and a community of developers like you.

Get Started    

AUTH

You can define one or more authentication methods in the "auth" section. Each auth method should have a unique key, because this key will be referenced in workflows.

To define an auth method, first choose a unique name as the key, then assign the auth type, which is the authentication method that the service provider is utilizing to authenticate and authorize API requests.

{
  "auth": {
    "my-auth": {
      "type": "oauth2",
      "configuration": {
        ...
      }
    }
  }
}

Currently we support these auth types:

Each auth type must be properly configured. The configuration varies based on the auth type. Please read the appropriate section(s) for details.

OAuth2

An OAuth2 definition contains the following attributes:

  • type
  • configuration
  • defined_fields [Optional]

type

Must match exactly: oauth2

configuration

Default: {}

The OAuth 2 configuration is a JSON object that contains the following items.

📘

Note

For more information regarding OAuth2: Official OAuth 2 Documentation

Key

JSON Type

Required

authorization_base_url

string

yes

client_id

string

yes

client_secret

string

yes

scopes

array

yes, use empty array if no scope is specified

token_request_body

string

no

token_url

string

yes

refresh_url

string

no

include_client_id

boolean

no

authorization_base_url

The authorzation_base is the location where we will send the user to authorize access to your integration for their account on the service provider.

It is this URL that will confirm your client_id, and scopes on the service provider and prompt the user to give authorization.

client_id

Default: '' (Empty String)

The client_id should be given to you by the service for which you are creating the integration. The client_id acts as a public identifier for your integration.

Most service providers provide a unique, hard-to-guess string.

client_secret

Default: '' (Empty String)

The client_secret should be given to you by the service for which you are creating the integration. The client_secret is like your password for a service. It is a secret known only to your integration and the service provider.

Most service providers provide a large cryptographically-secure string.

scopes

Default: [] (Empty List)

A scope in OAuth terms specify exactly what access your application needs to have to a user's account for given service. It is important to note that scopes do not grant additional permissions beyond what the user already has within the service.

👍

TIP

For more information on OAuth Scopes, visit https://oauth.net/2/scope/

Every service defines scope differently, and are usually related to the business logic of the service. If no scopes are required by the service provider, provide an empty list.

token_request_body

token_request_body is an optional parameter. If your OAuth server requires additional information as part of the token request, you can add that information here. If this field is not utilized, do not include it in the configuration.

token_url

Once a user has authorized your integration, the token_url will be used to obtain the OAuth access token.

refresh_url

The refresh_url is an optional parameter. This URL is used to refresh expired OAuth access tokens. Do not include this field in the configuration if you OAuth server doesn't support/require refreshing tokens.

include_client_id

include_client_id is an optional parameter to control where to include OAuth credentials when exchanging/refreshing access tokens with your OAuth server. This defaults to false.

📘

More about include_client_id

We support including OAuth client credentials in two standard ways when making requests to retrieve or refresh access tokens (via either token_url or refresh_url). The value for include_client_id should be set appropriately based on how your OAuth server is implemented.

  • Set this field to true if your OAuth server expects additional request parameters client_id and client_secret
  • Set this field to false if your OAuth server expects the client ID and secret in BasicAuth format in the HTTP header

See section 2.3.1 of RFC6749: OAuth 2.0 Core for details about this standard and its alternative.

defined_fields

This optional section allows for the definition of a subdomain field. If the subdomain field is defined, the subdomain value becomes available to use throughout your configuration.

The following attributes are used to describe how the defined fields should be presented to the user:

Attribute

JSON Type

Required

label

string

yes

placeholder

string

yes

help_text

string

yes

Example

Here is an example of an OAuth2 config

{
  "auth": {
    "my_oauth2_configuration": {
      "type": "oauth2",
      "configuration": {
        "authorization_base_url": "https://api.example.com/oauth2/authorize",
        "client_id": "woef2qo3hefawWEWrfh2qe21wlvdflkefnqs",
        "client_secret": "[insert your secret here]",
        "scopes": [
          "insert_scope_here_if_needed"
        ],
        "token_url": "https://api.example.com/oauth/token",
        "refresh_url": "https://api.example.com/oauth/authorize"
      }
    }
  }
}

Example With Subdomain

Here is an example of an OAuth config with the optional subdomain field:

{
  "auth": {
    "my_oauth2_configuration": {
      "type": "oauth2",
      "configuration": {
        "authorization_base_url": "https://${subdomain}.example.com/oauth2/authorize",
        "client_id": "woef2qo3hefawWEWrfh2qe21wlvdflkefnqs",
        "client_secret": "[insert your secret here]",
        "scopes": [
          "insert_scope_here_if_needed"
        ],
        "token_url": "https://${subdomain}.example.com/oauth/token",
        "refresh_url": "https://${subdomain}.example.com/oauth/authorize"
      },
      "defined_fields": {
        "subdomain": {
          "label": "Account Subdomain",
          "placeholder": "Enter your Account Subdomain",
          "help_text": "Your subdomain immediately precedes the .example.com portion of your Example url."
        }
      }
    }
  }
}

For more information on using the subdomain value, see the section on Subdomain Data.

Callback redirect URL

Some authorization servers will require you to register the redirect URL or add it to an allow-list. The redirect URL that you should register with your authorization server is:

https://integration-layer-siphon.cluster.app-us1.com/auth/callback

BasicAuth

A BasicAuth definition must contain the following attributes:

  • type
  • defined_fields
  • verify_url

type

Must match exactly: basic

verify_url

This is required to validate user-provided credentials.

📘

Expected behavior for verify_url:

We make a "GET" request to this URL using the basic auth credentials provided by the user, and expect a 200 response. All other status codes will mark the credentials as invalid.

defined_fields

This section defines the username/password fields users see when supplying BasicAuth credentials. In addition, this is the place to define the optional subdomain field. If the subdomain field is defined, the subdomain value becomes available to use throughout your configuration.

When specifying the BasicAuth credential fields, you must define both "username" and "password".

The following attributes are used to describe how the defined fields should be presented to the user:

Attribute

JSON Type

Required

label

string

yes

placeholder

string

yes

help_text

string

yes

Example

Here is an example of a BasicAuth config:

{
  "auth": {
    "my_basic_auth": {
      "type": "basic",
      "verify_url": "https://api.example.com/ping",
      "defined_fields": {
        "username": {
          "label": "Email",
          "placeholder": "Enter Email for Your Account",
          "help_text": "This is the email used to register your account"
        },
        "password": {
          "label": "Secret",
          "placeholder": "Enter Your Account Secret/Password",
          "help_text": "If you don't know your password, you can request a reset here: https://account.example.com/forgot"
        }
      }
    }
  }
}

The above config will produce the following auth UI:

Example With Subdomain

Here is an example of a BasicAuth config with the optional subdomain field:

{
  "auth": {
    "my_basic_auth": {
      "type": "basic",
      "verify_url": "https://${subdomain}.example.com/ping",
      "defined_fields": {
        "username": {
          "label": "Email",
          "placeholder": "Enter Email for Your Account",
          "help_text": "This is the email used to register your account"
        },
        "password": {
          "label": "Secret",
          "placeholder": "Enter Your Account Secret/Password",
          "help_text": "This is the password used to access your account"
        },
        "subdomain": {
            "label": "Account Subdomain",
            "placeholder": "Enter Your Account Subdomain",
            "help_text": "You subdomain can be found by looking at your account url: https://{subdomain}.example.com/ "
        }
      }
    }
  }
}

For more information on using the subdomain value see the section on Subdomain Data.

INSERT IMAGE HERE

Token Auth

Token-based auth must contain the following attributes:

  • type
  • header_key
  • token_prefix
  • verify_url
  • defined_fields

type

Must match exactly: token

header_key

This is the key that should be used in HTTP headers to contain the token. For example, "Authorization".

token_prefix (optional)

This is the prefix to be prepended in the token value. For example, "Token". This will cause the token to be formatted as "TOKEN user_provided_token"

verify_url

This is required to validate the token provided by the user.

📘

Expected behavior for verify_url:

We make a "GET" request to this URL using the basic auth credentials provided by the user, and expect a 200 response. All other status codes will mark the credentials as invalid.

defined_fields

Similar to defined_fields for BasicAuth, this section defines the token field users interact with when supplying the token value. This section can also accommodate an optional subdomain field. If the subdomain field is defined, the subdomain value becomes available to use throughout your configuration.

For Token Auth, you must specify the token field.

The following attributes are used to describe how the defined fields should be presented to the user:

Attribute

JSON Type

Required

label

string

yes

placeholder

string

yes

help_text

string

yes

Example

Here is an example of a token auth config

{
  "auth": {
    "my_token_auth": {
      "type": "token",
      "verify_url": "https://api.example.com/token_verify",
      "header_key": "API-TOKEN",
      "token_prefix": "Token",
      "defined_fields": {
        "token": {
          "label": "Token",
          "placeholder": "Enter the API Token for Your Account",
          "help_text": "You can find your token in your account settings."
        }
      }
    }
  }
}

Our system will generate the UI below for this config:

Example With Subdomain

Here is an example of a TokenAuth config with the optional subdomain field:

{
  "auth": {
    "my_token_auth": {
      "type": "token",
      "verify_url": "https://${subdomain}.example.com/token_verify",
      "header_key": "API-TOKEN",
      "token_prefix": "Token",
      "defined_fields": {
        "subdomain": {
          "label": "Account Subdomain",
          "placeholder": "Enter Your Account Subdomain",
          "help_text": "You subdomain can be found by looking at your account url: https://{subdomain}.example.com/ "
        },
        "token": {
          "label": "Token",
          "placeholder": "Enter the API Token for Your Account",
          "help_text": "You can find your token in your account settings."
        }
      }
    }
  }
}

For more information on using the subdomain value see the section on Subdomain Data.

Updated 26 days ago


What's Next

API

AUTH


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.