Overview

CleverTap uses a header-based authentication model to authenticate requests to the API. Every CleverTap API call should include Account ID and Account Passcode as the request headers. Suppose your CleverTap admin has opted for User-Passcode instead of Account Passcode. In that case, you must use your User-Passcode in the passcode header. The CleverTap API expects these values to be keyed in as X-CleverTap-Account-Id and X-CleverTap-Passcode.

Account Passcode Vs. User Passcode

There can be situations where it becomes risky to give away the account passcode of your CleverTap account to people inside and outside of your organization. It exposes your account to security risks. Therefore, it is best to grant user passcodes to specific users who would use CleverTap APIs instead of account passcode.

Obtain Your Account Credentials

To obtain account credentials, log in to the CleverTap dashboard and navigate to Settings > Project page.

📘

Create Account Passcode

You can also create an account passcode from the Projects page by clicking the +Passcode link. by clicking, you are navigated to the Passcodes page. For more information about the steps involved, refer to Create Account Passcode.

Example

Here is an example cURL request to the Events API showing the headers needed to authenticate the request from the account in the India region.

curl "https://in1.api.clevertap.com/1/events.json?cursor=CURSOR_VALUE" \
-H "X-CleverTap-Account-Id: YOUR_ACCOUNT_ID" \
-H "X-CleverTap-Passcode: YOUR_ACCOUNT_PASSCODE OR YOUR_USER_PASSCODE" \
-H "Content-Type: application/json"

require 'net/http'
require 'uri'
uri = URI.parse("https://api.clevertap.com/1/events.json?cursor=CURSOR_VALUE")
request = Net::HTTP::Get.new(uri)
request.content_type = "application/json"
request["X-Clevertap-Account-Id"] = "YOUR_ACCOUNT_ID"
request["X-Clevertap-Passcode"] = "YOUR_ACCOUNT_PASSCODE"
req_options = {
  use_ssl: uri.scheme == "https",
}
response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end
puts response.body

The following table lists down the API endpoint host for the region of your account:

Account-level Passcode for APIs

You can have multiple account-level passcodes rather than having a single account passcode used across different partners. This offers better security when using CleverTap APIs.

Account passcodes can be unique to each partner. Only admins or users with write access to the User Settings page can grant passcodes. They can create up to 100 passcodes.

Create Account Passcode

To create an account passcode:

1. Navigate to Settings > Passcodes.
2. Click + Passcode.

The Generate Passcode page displays.

3. Enter the following details:

4. Click Create & View. On clicking, the passcode displays.
5. Click API Key to copy it and then click Done.

📘

Save Passcode for Later Use

For security reasons, the passcode cannot be shown again. Copy the key and save it for later use.

The new passcode is now visible under the Passcodes page.

📘

Passcode Status

• An email notification is sent when the passcode is nearing expiration or has expired.
• The status of the passcode is displayed as Expiring soon from the 30 days of expiration.
• An error message displays when using the expired passcode to authenticate with CleverTap API.
• After the passcode expires, we recommend deleting the passcode.

Edit Account Passcode

To edit account passcode:

1. Navigate to Settings > Passcodes and then click icon for the passcode you want to edit. The Edit Passcode page opens.

2. Modify the required fields and then click Update.

Delete Account Passcode

Navigate to Settings > Passcodes and then click icon for the passcode you want to delete. On deleting the passcode, the APIs will stop working.

User Passcode for APIs

For API authentication, you can enforce dashboard users to use user passcode rather than account passcode. User passcode offers a better security standard while using CleverTap APIs.

User passcodes are unique to each user and granted by the admin.

Enable User Passcode For a User

1. If you are an admin user, go to Settings > Users to enable user passcode.
2. Select the user from the list and click Grant.

When you grant the passcode to a user, you need to specify the period for which the passcode remains valid.
You can from the following options:

After you grant the user a user passcode, the user can see their user passcode on the Settings page as shown in the following figure:

Reset and Revoke User Passcode

An admin can reset or revoke an existing user passcode by navigating to the Users page and selecting the required action.

• Reset Passcode generates a fresh new passcode for the user. Post resetting, the user has to incorporate the new passcode to APIs.

• Revoke Passcode invalidates the existing passcode for the user, and the user can no longer fire API calls using their passcode.

Next Steps

Now that you understand how to authenticate with the CleverTap API, you are ready to make your first API call.

Start with Get User Profiles API, which shows you how to request User Profiles from CleverTap.