Authentication

All API requests require OAuth 2.0 authentication. You must first create API credentials in your Automation instance, then use them to obtain an access token.

Step 1: Create API Credentials

1. Navigate to Settings → API Credentials in your Automation instance (/s/credentials/new)
2. Enter a Name for your application
3. For Authorization Code flow: add your Redirect URI(s)
4. Save — you'll receive a Client ID and Client Secret

info

Client Credentials grant type is only available for credentials created by admin users. Non-admin users can only use the Authorization Code flow.

Step 2: Obtain an Access Token

Client Credentials

Best for server-to-server integrations where no user interaction is needed.

curl -X POST https://{your-domain}/oauth/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}"

Authorization Code

Best for user-delegated access where a user authorizes your application.

1. Redirect the user to authorize:

GET https://{your-domain}/oauth/v2/authorize
  ?client_id={client_id}
  &response_type=code
  &redirect_uri={your_redirect_uri}

2. User logs in and approves access. They are redirected back to your URI with a code parameter.

3. Exchange the code for a token:

curl -X POST https://{your-domain}/oauth/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "code={authorization_code}" \
  -d "redirect_uri={your_redirect_uri}"

Token Response

{
  "access_token": "YTc3M2UxYzYxN2Y...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": null,
  "refresh_token": "NTJjNjAzOGI3MT..."
}

Field	Description
access_token	The token to include in API requests
expires_in	Token lifetime in seconds (default: 3600 — 1 hour)
token_type	Always Bearer
refresh_token	Use this to obtain a new access token without re-authenticating

Step 3: Use the Token

Include the access token in the Authorization header of every API request:

curl https://{your-domain}/api/contacts \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

Refreshing Tokens

Access tokens expire after 1 hour by default. Use the refresh token to get a new access token without requiring the user to re-authorize:

curl -X POST https://{your-domain}/oauth/v2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "refresh_token={refresh_token}"

Refresh tokens expire after 14 days by default.