OAUth2 Authentication

The OAuth 2.0 Authorization Framework is formalized in RFC-6749. Our IAM (Identity and Access Management) solution provides the Client Credentials flow for machine-to-machine integrations with our API.s

Client Credentials flow

The Client Credentials flow is ideal for machine-to-machine integrations. As an API consumer, all you need is a client ID and client secret to authenticate your application with the APIs.

Requesting an access token

In order to manually request a token, you can use one of the following methods

Basic auth header

• Retrieve the Token URL from the API you want to access,
• Create a Basic Authorization header:
  • Base64Encode("${clientId}:${clientSecret}")
• Send a POST request to the Token URL :
  • Header:
    • Content-Type: application/x-www-form-urlencoded
    • Authorization: Basic <ENCODED AUTHORIZATION>
  • Body: grant_type="client_credentials"

A sample curl-request is shown below:

curl --location '<TOKEN URL>' \
     --header 'Authorization: Basic <ENCODED AUTHORIZATION>' \
     --form 'grant_type="client_credentials"'

Post request with credentials in the body

• Retrieve the Token URL from the API you want to access,
• Send a POST request to the Token URL :
  • Body: grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}

A sample curl-request is shown below:

curl -s <TOKEN URL> -d "grant_type=client_credentials&client_id=${clientId}&client_secret=${clientSecret}"

Refreshing an access token

As specified in the OAuth2 specification (RFC-6749), the Client Credentials flow does not support refresh tokens. When a response is returned with a HTTP/401 status code, it is up to the client to refresh its access tokens. This is typically handled through an interceptor on the API calls which makes the refreshes transparent from the point of view of the client application logic.

Rate limiting

For security and reliability reasons, the OAUth2 endpoints are protected with rate-limiting. Up to 50 requests per second from the same IP are allowed, further requests will be rejected with a 429 response code.

In case we detect suspicious behavior such as continuous failed login attempts from the same IP, the IP will be temporarily blocked. When this happens, you will start seeing connection errors, ssl/tls handshake errors or something similar.