OAuth 2.0 Authentication

TaxBandits API incorporates OAuth 2.0, the standard authorization mechanism that enables your software to access the resources hosted by TaxBandits.

This authentication scheme involves JSON Web Tokens (JWT), which are access tokens generated by the server in response to a request.

• To start the OAuth 2.0 Authentication, you must retrieve the API keys (User Token, Client ID, Client Secret) in the sandbox console.

• Once done, you must request the access token. To request an access token, you need to create a JWS (JSON Web Signature) for Authentication. The JWS consists of 3 parts, as given below:

Header:

{
    "alg": "HS256", /*Algorithm = HS256*/
    "typ": "JWT" /*Type = JSON Web Token (JWT)*/
}

Payload:

{
    "iss": "968a9c78dae29a29",  /*Issuer: Client ID retrieved from the console site*/
    "sub": "968a9c78dae29a29",  /*Subject: Client ID retrieved from the console site*/
    "aud": "a574b75f18b24fc09f9039ffb5cb08f3", /*Audience: User Token retrieved from the console site*/
    "iat": 1516239022 /*Issued at: Number of seconds from Jan 1 1970 00:00:00 (Unix epoch format)*/
}

Signature:

    HMACSHA256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload),
    siqHfLy59g3UHxrb5gjxg  /*Client Secret retrieved from the console site*/

 )

• Combine the Header, payload, and signature to generate the JWS.

Sample JWS

   eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOi
   I5NjhhOWM3OGRhZTI5YTI5Iiwic3ViIjoiOTY4YTljNzhkYWUyOWEyOSIsImF1
   ZCI6ImE1NzRiNzVmMThiMjRmYzA5ZjkwMzlmZmI1Y2IwOGYzIiwiaWF0IjoxN
   TE2MjM5MDIyfQ.HNQznxlPyVt62kyUeVwtk1-uzm1uDWH4NBDLShA6Ac0

• Once the JWS is generated, send a request to the Authentication Server URL for an Access token. Refer below to learn how to get the JWT from TaxBandits API.

Authentication Server URL:

Sandbox: https://testoauth.expressauth.net/v2/tbsauth

Live: https://oauth.expressauth.net/v2/tbsauth

GETv2/tbsauth

In order to send a GET request to the TaxBandits Authentication Server URL, you must pass the JWS in the “Authentication: {JWS Value}” HTTP Header.

Sample Code:

Node JS

try {
  /* PUBLIC API OAUTH (GETTING JWT TOKEN USING JWS TOKEN) v2 */
  const oauthResponse = await axios.get(`https://testoauth.expressauth.net/v2/tbsauth`, {
    headers: {
      Authentication: signature, // Pass JWS as Authentication in headers
    },
  });
  console.log(oauthResponse.data.AccessToken);
} catch (e) {
  console.error(e.response.data.StatusMessage);
}

• Once we receive a JWS from you, TaxBandits will provide the JWT (Access token) as a response.

Following are the parts of the JWT response you receive

Header:

{
    "alg": "HS256", /*Algorithm = HS256*/
    "typ": "JWT" /*Type = JSON Web Token (JWT)*/
}

Payload:

{
  "iss": "https://testoauth.expressauth.net/v2/",
  "sub": "9f3e403de1d9a3d2",
  "aud": "ca64d73230a44d2682937b6844fbc528",
  "iat": 1694585458,
  "exp": 1694589058
}

Signature:

HMACSHA256(
     base64UrlEncode(header) + "." +
     base64UrlEncode(payload),
     siqHfLy59g3UHxrb5gjxg /*Master Secret Key*/
)

Here is the sample JWT response you will receive:

{
    "StatusCode": 200,
    "StatusName": "Ok",
    "StatusMessage": "Successful API call",
    "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL3Rlc3RvYXV0aC5leHByZXNzYXV0aC5uZXQvdjIvIiwic3ViIjoiOWYzZTQwM2RlMWQ5YTNkMiIsImF1ZCI6ImNhNjRkNzMyMzBhNDRkMjY4MjkzN2I2ODQ0ZmJjNTI4IiwiaWF0IjoxNjk0NTg1NDU4LCJleHAiOjE2OTQ1ODkwNTh9.WPOCs-lxo3GXz7_zGGmQovWZy4WD0smW7n-U-InuoXE",
    "TokenType": "Bearer",
    "ExpiresIn": 3600,
    "Errors": null
}

Server Time

To request an access token, you need to create a JWS (JSON Web Signature) for Authentication. The Payload of the JWS will contain the following parameters:

• Issuer "iss"
• Subject "sub"
• Audience "aud"
• Issued at "iat"

The JWT will be returned in the Response only when the iat value matches our server time. If the iat value does not match, then you will get the error "401 - Invalid 'iat' value in request".

You can use the GetServerTime endpoint to get the timezone, current date, and time of our server. This helps you make sure that the server time of your application is aligned with our API’s server time.

One of the reasons why the server times may mismatch is that your Windows time might not have synced. In that case, you can try synchronizing your time with the Windows time zone server and check if the times match.

GETgetservertime 

Response Body

Field	Type	Description
StatusCode	Number	Returns the status codes like 200,300 etc
StatusName	string	Name of the status code
StatusMessage	string	Detailed status message
ServerDate	string	TaxBandits API server current date
ServerTime	string	TaxBandits API server current time
TimeZone	string	TaxBandits API server time zone
UnixTs	string	Unix time stamp of TaxBandits API server time
Errors	object[]	Shows error information
Id	string	Returns the validation error Id
Name	string	Name of the validation error
Message	string	Description of the validation error

Response JSON

{
    "StatusCode": 200,
    "StatusName": "Ok",
    "StatusMessage": "Successful API call",
    "ServerDate": "10/10/2023",
    "ServerTime": "06:05:48",
    "TimeZone": "UTC",
    "UnixTs": "1696917948",
    "Errors": null
}