Skip to main content
Version: 1.7.3

OAuth 2.0 Authentication

TaxBandits uses OAuth 2.0 as the standard authorization protocol, allowing your application to securely access TaxBandits resources via token-based authentication.

OAuth 2.0 is implemented using JSON Web Tokens (JWT), where you authenticate using a signed token (JWS) and receive an access token (JWT) in return. This access token is used in subsequent API calls.

1. Get Your API Credentials​

Before you begin:

  • Log in to the TaxBandits Developer Console.
  • Retrieve the following credentials:
    • Client ID
    • Client Secret
    • User Token

2. Generate a JWS (JSON Web Signature)​

To request an access token, first create a JWS using the credentials above.

{
    "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

3. Send Authentication Request​

Once the JWS is generated, send a request to the Authentication Server URL for an Access token. You must pass the JWS token in the Authentication header.

Authentication Server URL:​

GETv2/tbsauth
Run in Postman

4. Receive Access Token (JWT)​

Following are the parts of the JWT response you will 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
}

Sync with Server Time​

When generating the JWS (JSON Web Signature) to request your access token, the iat (Issued At) field in the payload must match the current server time from TaxBandits within an acceptable window. If there's a significant mismatch, your request will be rejected with:

Unauthorized Response - You'll get the below response when your API requests don't contain valid authentication credentials.

{
    "StatusCode": 401,
    "StatusName": "Unauthorized",
    "StatusMessage": "Invalid authorization credentials",
    "Errors": [
        {
            "Id": "AUTH-100018",
            "Name": "Authorization",
            "Message": "JWT EXPIRED"
        }
    ]
}

Why server time matters​

OAuth 2.0 authentication with JWS is time-sensitive. The iat value (a Unix timestamp) tells our server when the token was generated. If your system clock is even slightly off—especially on Windows or virtual machines—it can result in failed authentication.

How to stay in sync​

Use the GetServerTime endpoint to align your application's system time with TaxBandits' API server time. This endpoint returns the current server time, date, timezone, and corresponding Unix timestamp.

GETv2/getservertime
Run in Postman