Authentication

Understand how CleverTap authenticates API requests

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 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.

10781078 22382238

📘

Create Account Passcode

You can also create an account passcode from the Projects page by clicking the +Passcode link. On 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.
27222722

The Generate Passcode page displays.

630630
  1. Enter the following details:

Field

Description

Passcode Name

Enter the name to uniquely identify the passcode.

Set Expiry Date

Select from the available options:

  • Set day(s): Enter the number of days after which the passcode will expire.
  • Forever: Select this option if you do not want the passcode to expire.
  1. Click Create & View. On clicking, the passcode displays.
  2. 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 passcode status 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 EditEdit icon for the passcode you want to edit. The Edit Passcode page opens.
578578
  1. Modify the required fields and then click Update.

Delete Account Passcode

Navigate to Settings > Passcodes and then click DeleteDelete 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 the user passcode.
  2. Select the user from the list and click Grant.
22842284

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:

Field

Description

Finite

Indicates that the passcode can be valid for a specific period (1-365 days).

Infinite

Indicates that the passcode never expires.

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:

22382238

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 into APIs.
22842284
  • Revoke Passcode invalidates the existing passcode for the user, and the user can no longer fire API calls using their passcode.
22842284

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.


Did this page help you?