Authentication

OAuth 2.0 has become the "industry-standard protocol for authorization", and we use it to secure our API. In order to authenticate with our servers using the OAuth 2.0 flow, you'll need to grab a client ID and a client secret from the Settings → Integrations & Plugins → Cerkl API v3 page in the application. Hit the "Generate New OAuth Credentials" button and name your new OAuth 2.0 client credentials something useful.

Be sure to save your client credentials — we can only display your client secret once. You will be using these credentials to work with Cerkl API v3 in your codebase, on our API Reference page, and in Postman. If you do lose your credentials don't worry — it's really just a minor inconvenience. You can generate another client ID and client secret using the same method described above.

Getting an Access Token

Once you have your client credentials, you will need to authenticate with our OAuth 2.0 server to receive an access token. This token is your key to using Cerkl API v3 in your codebase, "the thing that applications use to make API requests on behalf of a user" if you will. Visit this page to read more about OAuth 2.0 access tokens.

To authenticate with your client credentials and receive an access token, it depends on how you are working with Cerkl's API.

Authenticating Programmatically

To authenticate within your codebase, use any library/tool capable of making HTTP requests to POST your client credentials to our OAuth 2.0 token endpoint. Using cURL, you might end up with something like this:

$ curl -v https://api.cerkl.com/v3/oauth/Token \
    -H "Accept: application/json" \
    -H "Accept-Language: en_US" \
    -u "{client_id}:{client_secret}" \
    -d "grant_type=client_credentials"

Using valid client_id and client_secret credentials, you should receive an access token upon successful completion of your request to our OAuth 2.0 server. You can use this access token in your code to start making useful API calls and integrating your systems.

Authenticating in Postman and the API Reference

Authenticating in Postman and our API Reference page is straightforward and can be done completely via UI elements. Visit those documentation pages for more information.

Access Token Lifetime

As a point of security, the access tokens we issue only last 12 hours. In the event your processes that use our API take longer than that, we recommend splitting your integration tasks up into multiple jobs or implementing token regeneration functionality.