Skip to main content
Version: 1.7.0

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.

API Credentials

  • 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
Run in Postman

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.

  • 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
}

Sample Code:

Send the above-listed parameters using a code to decrypt the PDF URL for download. Here is a sample code for NodeJs.

const axios = require("axios");
const jwt = require("jsonwebtoken");

const generateJWT = async (clientId, clientSecret, userToken) => {
try {
// Generate JWS value
const signature = generateJWS(clientId, clientSecret, userToken);

// Getting JWT by requesting OAUTH Server
const oauthResponse = await axios.get('https://testoauth.expressauth.net/V2/tbsauth', {
headers: {
Authentication: signature // Pass JWS as Authentication in headers
}
});

console.log('TaxBandits JWT:', oauthResponse?.data?.AccessToken)
} catch (e) {
console.log("Error in JWT:", e?.response?.data)
}
}

const generateJWS = (clientId, clientSecret, userToken) => {
try {
const payload = {
"iss": clientId,
"sub": clientId,
"aud": userToken,
"iat": Math.floor(new Date().getTime() / 1000)
}

const jwsToken = jwt.sign(payload, clientSecret);

return jwsToken;
} catch (e) {
console.log("Error in JWS: ", e)
}
}

const clientId = "<<TaxBandits Client Id>>" // Client ID retrieved from the console site
const clientSecret = "<<TaxBandits Client Secret>>" // Client Secret retrieved from the console site
const userToken = "<<TaxBandits User Token>>" // User Token retrieved from the console site

generateJWT(clientId, clientSecret, userToken)

Once the JWT is obtained, you can use that token to access the Authorization Server URL. This JWT will expire after an hour.

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.

GETv2/getservertime 
Run in Postman

Response Body

FieldTypeDescription
StatusCodeNumberReturns the status codes like 200,300 etc
StatusNamestringName of the status code
StatusMessagestringDetailed status message
ServerDatestringTaxBandits API server current date
ServerTimestringTaxBandits API server current time
TimeZonestringTaxBandits API server time zone
UnixTsstringUnix time stamp of TaxBandits API server time
Errorsobject[]Shows error information
    IdstringReturns the validation error Id
    NamestringName of the validation error
    MessagestringDescription 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
}