Basic Authentication: OAUTH2 (PHP, Curl, Postman, Excel VBA, Clover DX etc.)

Introduction

TrackTik uses OAuth 2 for its authentication.

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices. This specification and its extensions are being developed within the IETF OAuth Working Group.

More information is available at OAuth 2.0 — OAuth.Required Elements for Authentication

To authenticate with the TrackTik API, four pieces of identification information are needed:

1. Client ID (From OAuth 2 Client Record, which TrackTik will provide).
2. Client Secret (From OAuth 2 Client Record, which TrackTik will provide).
3. Employee username or email address of the TrackTik portal employee account, which TrackTik will provide.
4. Employee password: the password of the TrackTik portal employee account, which TrackTik will provide.

The OAuth 2 Access Token request endpoint is:

https://<domain>/rest/oauth2/access_token

Code Sample (PHP+Curl) and Postman Setup

$portal = 'https://<domain>/rest/oauth2/access_token';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $portal);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, array(
       'client_id'     => "d6543cb8...",
       'client_secret' => "bdc6ed2e...",
       'username'      => "username",
       'password'      => "smart password that isn't 12345",
       'grant_type'    => 'password'
));
$data = curl_exec($ch);
$auth_string = json_decode($data, true);
$access_token = $auth_string["access_token"];
$refresh_token = $auth_string["refresh_token"];
curl_close($ch);

Excel VBA How-To

Excel VBA function

Public Function getauth()
   Url = "https://<domain>/rest/oauth2/access_token?"
   sBody = "grant_type=password"
   sBody = sBody & "&client_id=****"
   sBody = sBody & "&client_secret=****"
   sBody = sBody & "&username=***@****"
   sBody = sBody & "&password=****"
   Set objhttp = CreateObject("MSXML2.ServerXMLHTTP")
   objhttp.Open "POST", Url, False
   objhttp.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
   objhttp.send CVar(sBody)
   Debug.Print objhttp.responseText
End Function

NB: In later versions of Visual Basic that utilize .NET, you can't use variable declarations like Let and Set (you can use Dim instead). Also, the data to pass to methods of objHTTP.* need to be enclosed in () like functions.

E.g.

Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP")
becomes…
Dim objHTTP = CreateObject("MSXML2.ServerXMLHTTP")

E.g.
objHTTP.Open "POST", Url, False
becomes…
objHTTP.Open("POST", Url, False)

Additional Documentation

Excel VBA Project in VSCode with XVBA Extension
 

Clover DX OAuth 2 Authorization Flow How-To

When configuring an Authorization Flow for CloverDX ETL, it's important to know that it has its own service for catching access tokens via the Callback URL.

The Callback URL is generated per CloverDX instance and has its own port number. In most cases, the domain will be localhost.

E.g.

http://localhost:55216/clover/oauth2

When configuring the authentication of CloverDX ETL for use with TrackTik's API, we recommend the following:

1. Make sure that Provider is set to "Generic".
2. In the Advanced tab of the CloverDX configuration panel, leave it blank, and it will pre-populate the Callback URL with a greyish text to suggest that it's not user-specified but automatically generated. Take note of it.
3. Edit the TrackTik API's OAUTH2 Client for that customer using CloverDX so that its redirect URL is that of CloverDX's auto-generated one. ([PATCH] https://<portal_domain>/rest/oauth2/oauth2-clients/{id})
4. "redirectUris":"http://localhost:55216/clover/oauth2"

N.B.: When performing the Authorization action from the CloverDX configuration panel, make sure to have checked the option to "Authorize using external browser" because the built-in HTML popup renderer won't capture the access token correctly.

Additional Documentation

• https://doc.cloverdx.com/latest/developer/oauth2-connections.html
• https://www.cloverdx.com/ty/webinar/working-with-oauth2-apis
• https://docs.clover.com/dev/docs/app-settings#

The API and Data Replication: access_token usage delay

The TrackTik API gets its data from a replication of web portal data. This is to prevent one from slowing down or locking the tables of the other. Given this, under heavy system loads, there can be delays between when an access_token is generated and received and when the first authenticated API call can be made.

If you find after getting an access_token that you intermittently experience 401 errors (works sometimes, others not), you should add a delay in your solution after the step of when you have the access_token before making subsequent API calls.