Authorization

CorrigoPro Direct uses OAuth 2.0 authorization flow to obtain a bearer to authorize API requests. Every call to this API must specify the Authorization HTTP header that includes the bearer token retrieved from the CorrigoPro OAuth server.

Authorization: Bearer {token}.

Example

Authorization: bearer pyeLrTJ99eJwBkDzLWzSksaAncLRCneyaW2P9FmhGRQSVlWB60jRqiGSN5ERqyqrRq_cE_zPW0DQAj15s_uctczFpPrFSqfwSIPDhBdhyJyQe_FSWNMASC2fL2EvTyPvFduJrbkhtcCnp_QrlH10KsJGwbe7uyhWIjkl-zhANI8YlLUEJGpZMd0Kq3V1roeqkYyHN7wSNNuElXd3VDyPAe2ivcb6ijVSFPmNmo9fG8-re4wpUV_pqMXmZJ2iqGJJ4TEY2_NL_Vf0Z7sYIAZgvOvDQqw-x0AmyLkje34cMLz88zK8

To request a token

Send a POST request to <OAuth Server URL> with the following body, encoded using the
application/x-www-form-urlencoded encoding algorithm:

• client_id: your client id from the configuration
• client_secret: your client secret from the configuration
• grant_type: constant value, set as "client_credentials"

Your sample cURL command may look like:

curl -i {OAUTH_SERVER_URL} -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id={YOUR_CLIENT_ID}&client_secret={YOUR_CLIENT_SECRET}"

A CorrigoPro authorization response may look like (with token lengths reduced to give better readability):

{   
    "access_token": "H4sIAAAAAAAEAG2NvQrCMBzE_..._aIS461GXB6FbggklBZcHy-3La5eU1pIfzF2A97A05_nE7HAAAA<---->y8cSRLtsNbsFkDhWAVZJjRp9rwSTNv77gTuD5CfIOHVjp-_..._boK6ZP8PHSOUZvRrnBbbyPHqc5f-wJQ",
    "token_type": "bearer",
    "expires_in": 1199
}

Use the obtained token for each request to the CorrigoPro Direct.

🚧

Deprecation Alert

The parameter "refresh_token" has been deprecated and will soon be removed.

Token Refreshes Recommendations

Parameter "expires_in" shows access token lifetime in seconds. For now, our server is configured to have an access token lifetime of 20 minutes (1200 seconds).

There are two approaches how to work with API using access token only.

• First approach (better performance) - once you've received an access token - cache it and use for all calls within it's lifetime. For this scenario possible 2 different way how to determine if access token still valid or not.
• Calculate and store token expiration time stamp and when the token is about to expire (for instance 1 minute left) or expired - call our OAuth server again and obtain a new access token.
• Just use the same token until our server not responds with HTTPCode = 401 UNAUTHORIZED and then you need to get a new access token.
• Second approach - call OAuth server before each API call. This approach can be used in case of small amount of calls to Direct API, otherwise this will dramatically hit performance of your integration.

Token validation

It is recommended to validate each request that your WebHook can receive. That is why CorrigoPro Direct sends each request with the bearer token inside the header. You can validate this token by using the following algorithm:

1. Split the token string into data and sign using this separator “<---->”.
2. Decode sign and data using Base64Url encoder.
3. Verify data by using sign and a public certificate.

To obtain the <client_id>, <client_secret>, <OAuth Server Url> and the public certificate, open the CorrigoPro Direct tile and turn the integration on.

IP Address Validation

For some, validating the source of the event notification by IP address may be desired.