Authentication

CleverTap uses a header based authentication model to authenticate requests to the API.

Overview

Every CleverTap API call should include both your Account ID and Account Passcode as the request headers. If your CleverTap admin has opted for User-Passcode instead of Account Passcode, you will have to use your User-Passcode instead in the passcode header. The CleverTap API expects these values to be keyed as X-CleverTap-Account-Id and X-CleverTap-Passcode.

Getting Your Account Credentials

Your CleverTap Account ID and Account/User Passcode are available on the Settings page. To navigate to the Settings page, log into your CleverTap account, click on the gear icon on the bottom left navigation, and select Settings dashboard.

Example

Here is an example cURL request to the Events API showing the headers needed to authenticate the request.

curl "https://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

Next Steps

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

Start with the Get Events API, which will show you how to request App Launch events from CleverTap.

User Passcode for APIs

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

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

How to enable user passcode for a user

If you are an admin user, To enable using user passcode, go to Settings -> Users. Pick a user from the list and click on Grant as shown below:

User passcode TTL (time to live)

When you grant the passcode to a user, you need to specify the time period until which the passcode remains valid. You can choose between Finite (1-365 days) and Infinite (never expire passcode).

Once you grant the user a user passcode, the user will be able to see her user passcode on her Settings page as shown below:

Resetting & revoking user passcode

Admin can reset or revoke an existing user passcode by going to the user's page and clicking on one of the options.

Reset passcode will generate a fresh new passcode for the user. Post resetting the user will have to incorporate the new passcode to APIs.
Revoke passcode will invalidate the existing passcode for the user and the user can no longer fire API calls using her passcode.

When to use user passcodes instead of account passcodes?

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

Updated 3 months ago


Authentication


Suggested Edits are limited on API Reference Pages

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