Generate Access Token API

This API is used to generate an access token using the client secret created from the CFC settings page. The generated access token can then be used to access the protected business resource APIs.

Rate limiting

This API is rate limited to a maximum of 288 requests per day per API client secret. This means that you can make up to 288 requests to the API in a 24-hour period using a single API client secret. If you exceed this limit, you will receive HTTP status code 429 Too Many Requests error.

The rate limit is reset every day at midnight UTC. This means that if you make your 288th request at 11:59 PM UTC, you will be able to make another request at 12:00 AM UTC.

To avoid hitting the rate limit, use caching to share the access token across multiple requests until the expiry datetime. This will help you to save requests and stay within the rate limit.

Request Method

GET

Request URL

{{BASE_URL}}/integration/v1/authz/token

Replace the {{BASE_URL}} with the one mentioned here for India (or here for KSA) based on whether you are using sandbox or production.

Request Headers

ParameterData TypeField ValidationsDescription

x-clear-client-secret

String

Cannot be empty.

Mandatory. API Client secret generated from Clear UI. Learn more

Request Path Params

There are no path parameters for this API.

Request Query Params

There are no query parameters for this API.

Request Body

There is no request body for this API.

Sample Request

curl --location --request GET 'https://api-sandbox.clear.in/integration/v1/authz/token' \
--header 'x-clear-client-secret: 3eboH/vsr2VpGNFqDSXzVs0yNj0fMDJToPjs71V3WATqLtmzf9kyNBZ24mCNRJsDj2tEe72PxFDOPccR579w=='

Response Status Codes

HTTP Status CodeDescription

200

For a successfully processed request.

401

If the user is not authenticated for the operation.

500

If there are any unhandled exceptions on Clear side.

Response Schema

ParameterData TypeField ConstraintsDescription

access_token

String

MaxLength: 256

Access token generated by Clear. If there is an error, then this field will not be returned.

valid_till

String

Format: ISO 8601.

YYYY-MM-DDTHH:MM:SS+00:00

Timestamp up to which the access token will be valid in UTC (GMT time zone). This period will be based on the expiration field set at the time of creation of API Client. If it was set as “Never expires”, then this value will be null. If there is an error, then this field will not be returned.

errors

Array

NA

Array of Error Details Objects. If there are no errors, this field will not be returned.

Error Details Object

ParameterData TypeField ConstraintsDescription

error_code

String

NA

Error code based on the rule or precondition that failed.

error_message

String

NA

Detailed error description.

error_source

String

NA

Source of the error. This will always be “CLEAR”.

error_id

String

NA

Unique ID of the error generated by Clear for unhandled errors and exceptions. If present, this ID may be quoted while raising a support case.

Be wary of duplicate or premature requests!

If you already have an access token which is not expired, and you make an API request to this endpoint from the same client secret, then you will receive a new access token and the existing access token will be revoked.

Sample Response

Success - HTTP Status Code - 200

{
  “access_token”: “1.2f205010-b96c-84ar-9dcd-5524c42eb99e_4d05f5b02559a70d65c958d15e1747b5c17512edf65a4b70d794a86bc77d9855”,
  “valid_till”:2023-04-11T20:21:24+00:00
}

Failure - HTTP Status Code - 401

If the client secret header key is missing OR If the client secret header value is null.

{
  "errors": [
    {
      "error_code": "CLI-SEC-001",
      "error_message": "Client secret header is missing or value is empty.",
      "error_source": "CLEAR",
      “error_id”: null
    }
  ]
}

Failure - HTTP Status Code - 401

If the client secret header value is incomplete, incorrect or invalid OR If the API client is deleted.

{
  "errors": [
    {
      "error_code": "CLI-SEC-002",
      "error_message": "Invalid or inactive client secret.",
      "error_source": "CLEAR",
      “error_id”: null
    }
  ]
}

Failure - HTTP Status Code - 401

If the client IP address is not within the whitelisted range.

{
  "errors": [
    {
      "error_code": "CLI-SEC-003",
      "error_message": "API Client IP is not within the allowed IP range.",
      "error_source": "CLEAR",
      “error_id”: null
    }
  ]
}

API Validations

There are no validations other than authentication in this API.

API Constraints

  1. This API needs to be authenticated with a valid client secret. If the client secret is missing, null, empty, invalid, incomplete or incorrect, the API will return HTTP Status Code 401.

  2. If the request is made from an IP address not in the range of allowed IPs set at the time of creation of the API client, then API will return HTTP Status Code 401.

  3. This API is rate limited to a maximum of 288 requests per day per API client secret. This means that you can make up to 288 requests to the API in a 24-hour period using a single API client secret. If you exceed this limit, you will receive HTTP status code 429 Too Many Requests error.

Keep it safe!

Access token is a confidential information. After creating an access token, it's important to persist it in a secure location.

FAQs on Access Token

Access token

Last updated