Authenticate

Get Started > API User Guide > Authenticate

Authenticate

Before you can use the API, you need to authenticate yourself. The API will validate your username and your API key, and return an authentication token if you are successfully authenticated.

You must include the authentication token in the header of all requests made to our API. All API requests must be made over HTTPS as requests made over HTTP will fail. There are 2 types of API credentials:

1. Sandbox API Credentials

Requests made to our Sandbox environment can be used to test our API before going live. Sandbox requests will return dummy responses, and no credit will be deducted from your account.

To use our Sandbox environment, please ensure all API requests are made to https://sandbox.cleardil.com

Example request:

curl -X POST https://sandbox.cleardil.com/v1/oauth2/token \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -u 'client_id:client_key'

Please ensure you replace client_id and client_key with the API credentials you have obtained from us.

Example response:

{
    "access_token":"your_access_token",
    "expires_in": 3600,
    "refresh_expires_in": 1800,
    "refresh_token": "your_refresh_token",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "your_session_state"
}

2. Live API Credentials

Live API Keys are generally only issued after the completion of integration testing. Requests made with the live API credentials require billing information.

To use our Live environment, please ensure all API requests are made to https://api.cleardil.com

Example request:

curl -X POST https://api.cleardil.com/v1/oauth2/token \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -u 'client_id:client_key'

Please ensure you replace client_id and client_key with the API credentials you have obtained from us.

Example response:

{
    "access_token":"your_access_token",
    "expires_in": 3600,
    "refresh_expires_in": 1800,
    "refresh_token": "your_refresh_token",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "your_session_state"
}

We have created a Postman API Collection to help you start testing as soon as possible. You can download our official Postman collection from our public github repository.

Postman is free application that allows you to quickly construct API calls, organise them in collections and share them with your team. To download Postman, simply follow this link.

3. Refresh Tokens

A Refresh Token is a special type of token that contains the information required to obtain a new Access Token. Usually, a user will need a new Access Token only after the previous one expires.

To refresh your token, using the Refresh Token you already obtained during authorization, make a POST request to the /oauth/token endpoint in the Authentication API, using grant_type=refresh_token.

curl -X POST 'https://sandbox.cleardil.com/v1/oauth2/token' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -u 'client_id:client_key' /
    -d 'grant_type=refresh_token&refresh_toke=your_refresh_token'

Please remember to replace your_refresh_token with the actual Refresh Token you have previously obtained during authorization.

The response will include a new Access Token, its type, its lifetime (in seconds).

Example response:

{
    "access_token":"your_access_token",
    "expires_in": 3600,
    "refresh_expires_in": 1800,
    "refresh_token": "your_refresh_token",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "your_session_state"
}

You should only ask for a new token if the Access Token has expired. For example, it’s a bad practice to call the endpoint to get a new Access Token every time you call an API.

You can read more about OAuth2 refresh token flow here.