API Reference

Authentication Setup

Introduction

There are two methods of authentication to Community's Data Export API:

  • API Tokens
  • Seat Context API

The authentication method best for your use case will depend on your infrastructure and the number of Community accounts that you manage.

API Tokens

Community's Data Export API uses an API Token system for authentication. If enabled for your account, the management interface for API Tokens can be found in the Community Dashboard, under Settings > API Tokens.

Connection Prerequisites

In order to authenticate to Community's Data Export API, you will require the following items:

  • One or more active Community accounts
  • An account seat with Data Export and Async REST API user enabled (will be enabled for you by Community team)
  • A valid API Token (prefixed with community_api, can be generated in Settings > Auth Tokens)

Authenticating to the Data Export API via API tokens

To authenticate a given request, you must include your API Token in an Authorization header field, such as Authorization: Bearer API_TOKEN.

Seat Context API

The Seat Context API offers an alternative way of authenticating to Community's Data Export API. This method is typically best when you are managing downloads from multiple Community accounts.

Connection Prerequisites

  • Multiple active Community accounts
  • An account seat with Data Export access enabled for each account you wish to access (will be enabled for you by Community team upon request)
  • A username / password combination for the account seat

Authenticating to the Data Export API via Seat Context API

The Seat Context API offers a set of endpoints for retriving the different accounts that a given Seat (email address) has access to in the Community system. This is typical of large enterprise deployments. If you are trying to download data for a single Community account, API Tokens are likely the best method.

Initial Authentication

To establish an initial login context, you must send a request to the POST Login endpoint.

You will receive a JSON response containing data about your login. For purposes of downloading data, the only field you need to use here is the token field. The provided JWT is valid for retrieving data for the given Client ID as stated in the Data Download guide.

Endpoint: POST https://dl.community.com/download/v2/auth/login

Request Headers:

content-type: application/json

Request Body:

{
  "password": "{{password}}",
  "email": "{{email}}"
}

Example Request:

curl --location --request POST 'https://dl.community.com/download/v2/auth/login' \
--data-raw '{
    "password": "your_account_password",
    "email": "your_account_email"
}'

Example Response:

{
    "seat_id": "2d40e1ca-d66a-4bde-b77e-c331eedb1a48",
    "client_id": "7b6240ad-37c4-4f55-84ac-f0d64584cbc9",
    "device_id": "9e43c975-0ba5-41cc-9488-9c9ccd0fa820",
    "token":
"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJKb2tlbiIsImRpZCI6IjgxYjU2MzIxLTYyYzAtNGViMC1iODZkLWVkOGEzZDRkZjI2MCIsImV4cCI6MTYyNTk0NjQ2NCwiaWF0IjoxNjI1ODYwMDY0LCJpc3MiOiJpZGVudGl0eSIsImp0aSI6IjJxODNlNzlzdHNsYnZyN2JlMDBiZzJlMSIsIm5iZiI6MTYyNTg2MDAwNCwic3ViIjoiOGQ3MDQ2NzctNWRhOC00Yzk3LWJjY2EtYTQ5NmRlMWY4ZDRkIn0.QfyDbhoo1cSa6EAWh41TeBfPUBpKjPmYBD4W8nlDex6mf5kWmbKMnzEsg2cn8d7x8GTisY-UBch72WeR4NQNFA",
    }

Example Response if Two-Factor Authentication is enabled:

{
    "seat_id": "2d40e1ca-d66a-4bde-b77e-c331eedb1a48",
    "token":
"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJKb2tlbiIsImRpZCI6IjgxYjU2MzIxLTYyYzAtNGViMC1iODZkLWVkOGEzZDRkZjI2MCIsImV4cCI6MTYyNTk0NjQ2NCwiaWF0IjoxNjI1ODYwMDY0LCJpc3MiOiJpZGVudGl0eSIsImp0aSI6IjJxODNlNzlzdHNsYnZyN2JlMDBiZzJlMSIsIm5iZiI6MTYyNTg2MDAwNCwic3ViIjoiOGQ3MDQ2NzctNWRhOC00Yzk3LWJjY2EtYTQ5NmRlMWY4ZDRkIn0.QfyDbhoo1cSa6EAWh41TeBfPUBpKjPmYBD4W8nlDex6mf5kWmbKMnzEsg2cn8d7x8GTisY-UBch72WeR4NQNFA",
    }

Two-Factor Authentication

If Two-Factor Authentication has been turned on for any Community Account that
the given Seat has access to, an additional API call will be required with the
six-digit code generated by the Seat's authentication app.

Endpoint: POST https://dl.community.com/download/v2/auth/login/callback/mfa

Request Headers:

Authorization: Bearer <jwt token from initial authentication>

Body

{
  "totp": "{{six-digit code}}"
}

Example Request

curl --location --request POST 'https://dl.community.com/download/v2/auth/login/callback/mfa' \
--header 'Authorization: Bearer {{token_id}}' \
--data-raw '{
   "totp" : "060229"
}'

Example Response:

{
    "seat_id": "2d40e1ca-d66a-4bde-b77e-c331eedb1a48",
    "client_id": "7b6240ad-37c4-4f55-84ac-f0d64584cbc9",
    "device_id": "9e43c975-0ba5-41cc-9488-9c9ccd0fa820",
    "token":
"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJKb2tlbiIsImRpZCI6IjgxYjU2MzIxLTYyYzAtNGViMC1iODZkLWVkOGEzZDRkZjI2MCIsImV4cCI6MTYyNTk0NjQ2NCwiaWF0IjoxNjI1ODYwMDY0LCJpc3MiOiJpZGVudGl0eSIsImp0aSI6IjJxODNlNzlzdHNsYnZyN2JlMDBiZzJlMSIsIm5iZiI6MTYyNTg2MDAwNCwic3ViIjoiOGQ3MDQ2NzctNWRhOC00Yzk3LWJjY2EtYTQ5NmRlMWY4ZDRkIn0.QfyDbhoo1cSa6EAWh41TeBfPUBpKjPmYBD4W8nlDex6mf5kWmbKMnzEsg2cn8d7x8GTisY-UBch72WeR4NQNFA",
    }

Retrieving Available Contexts

To retrieve a list of the available contexts (Community Accounts) accessible from a given Seat (email), you can use the GET Context endpoint.

The JSON response contains a single key: data. The associated value of this key is an array of the context objects available. Each context object represents a single Community Account, and is identified by the client_id value.

The client_id key in any of the returned context objects can be supplied to the Switch Context resource.

Endpoint: GET https://dl.community.com/download/v2/auth/context

Request Headers:

Authorization: Bearer <jwt token from initial authentication or two-factor authentication (if applicable)>

Request Body:

(none)

Example Request

curl --location --request GET 'https://dl.community.com/download/v2/auth/context' \
--header 'Authorization: Bearer {{token_id}}'

Example Response

{
  "data": [
    {
      "campaign_messages_monthly_threshold": 0,
      "campaign_messages_monthly_used": 0,
      "client_id": "de7f5827-b421-4404-9843-b1b56b956602",
      "current_context": *true*,
      "first_name": "Ted",
      "last_name": "Williams [DEMO]",
      "onboarding_billing_state": {
        "billing_provided": *false*,
        "billing_required": *false*,
        "trial_length_days": 14,
        "trial_started": *false*
      },
      "phone_number": "+15554441212",
      "phone_number_type": "ten_dlc",
      "roles": []
    }
  ]
}

Switching Contexts

As previously mentioned, to download data for multiple Leaders, you must first switch to the Context associated with each Leader, before calling the Downloads resources.

Use the client_id value from the Retrieve Contexts resource in the JSON body of this resource to switch Contexts. A successful PUT to this endpoint will return a new JWT that can be used to retrieve data resources as stated in the Data Download guide.

Endpoint: PUT https://dl.community.com/download/v2/auth/context

Request Headers:

Authorization: Bearer <jwt token from initial authentication or previous PUT>

Body

{
  "context": "{{client_id}}"
}

Example Request

curl --location --request PUT 'https://dl.community.com/download/v2/auth/context' \
--header 'Authorization: Bearer {{token_id}}' \
--data-raw '{
   "context" : "de7f5827-b421-4404-9843-b1b56b956602"
}'

Example Response

{
  "data": {
    "id": "de7f5827-b421-4404-9843-b1b56b956602",
    "seat_id": "8d704677-5da8-4c97-bcca-a496de1f8d4d",
    "token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJKb2tlbiIsImRpZCI6IjgxYjU2MzIxLTYyYzAtNGViMC1iODZkLWVkOGEzZDRkZjI2MCIsImV4cCI6MTYyNTk0NjczNSwiaWF0IjoxNjI1ODYwMzM1LCJpc3MiOiJpZGVudGl0eSIsImp0aSI6IjJxODNlbjJuazJ2cWVrMHZsazBiZ2lvMSIsIm5iZiI6MTYyNTg2MDI3NSwic3ViIjoiOGQ3MDQ2NzctNWRhOC00Yzk3LWJjY2EtYTQ5NmRlMWY4ZDRkIn0.7KVc2xGegnRr11YUQaR4YRuHIeWMHATqSwJFR3KeLn_syVtswsmYYJKkyvonlC_PTaKb01XsQQCcXI0XqMlAHw"
  }
}

Logging Out

By default, the session token obtained with the Login resource is valid for 7 days. You may wish to logout before then and expire the token using this resource. Use the token obtained in /login in the Headers. No body is required.

Endpoint: DELETE https://dl.community.com/download/v2/auth/logout

Request Headers:

Authorization: Bearer <token>

Request Body:

(none)

Help and Support

Having issues with authentication? Send us an email at [email protected] and we'll be able to help.

Updated 11 months ago

Did this page help you?

Updated 11 months ago

Did this page help you?