Get Token

POST 
/token

Username : App Key, Password : App Secret. These will shared by GTN.

A signed JWT token is used to get the access token to the open API services.

FinTech public key - need to generate as mentioned here

FinTech private key - need to generate as mentioned here

Assertion - This is a JWT token that will be generated from the client-server side and sent as a request parameter. This will be generated using, Fintech private key, institution app key and claims - institution code as instCode and server id as userId.

When generating JWT from the server side, you need to add the institution code and server id/ user id as claims.

INST_CODE : FinTech institution code is given by GTN

USER_ID : FinTech backend service's instance unique id

Recommend to use 1 server token over using multiple server tokens.

String INST_CODE = "instCode";
String USER_ID = "userId";
       
Map<String, String> payload = new HashMap<>();
payload.put(INST_CODE, instCode);
payload.put(USER_ID, userId);

Code Sample-

Java

   public static Algorithm getAlgorithm(String publicKey, String privateKey){
       return Algorithm.RSA256(getPublicKey(publicKey), getPrivateKey(privateKey));
   }
   private static RSAPrivateKey getPrivateKey(String privateKeyString){
       try {
           KeyFactory kf = KeyFactory.getInstance("RSA");
           byte[] pvtKeyBytes = base16Decoder(privateKeyString);
           PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(pvtKeyBytes);
           return (RSAPrivateKey) kf.generatePrivate(keySpec);
       } catch (Exception e){
           ...
       }
       return null;
   }


   private static java.security.interfaces.RSAPublicKey getPublicKey(String publicKeyString){
       byte[] pubKeyBytes = base16Decoder(publicKeyString);
       try{
           KeyFactory kf = KeyFactory.getInstance("RSA");
           RSAPublicKey pkcs1PublicKey = RSAPublicKey.getInstance(pubKeyBytes);
           BigInteger modulus = pkcs1PublicKey.getModulus();
           BigInteger publicExponent = pkcs1PublicKey.getPublicExponent();
           RSAPublicKeySpec keySpec = new RSAPublicKeySpec(modulus, publicExponent);
           return (java.security.interfaces.RSAPublicKey) kf.generatePublic(keySpec);
       } catch (IllegalArgumentException ie) {
           try {
               KeyFactory kf = KeyFactory.getInstance("RSA");
               X509EncodedKeySpec keySpec = new X509EncodedKeySpec(pubKeyBytes);
               return (java.security.interfaces.RSAPublicKey) kf.generatePublic(keySpec);
           } catch (Exception e) {
               ...
           }
       } catch (Exception e){
           ...
       }
       return null;
   }      
   public static byte[] base16Decoder(final String hex) {
       final byte[] bts = new byte[hex.length() / 2];
       for (int i = 0; i < bts.length; ++i) {
           bts[i] = (byte) Integer.parseInt(hex.substring(2 * i, 2 * i + 2), 16);
       }
       return bts;
   }

    long accessTokenExpiryTimeMs = 123123123234L;
    Date accessTokenExpiry = (new Date(System.currentTimeMillis() + accessTokenExpiryTimeMs));

    Algorithm algorithm= getAlgorithm(publicKey, privateKey);


   
   String assertion = JWT.create()
                   .withIssuer(APP_KEY)
                   .withPayload(payload)
                   .withExpiresAt(accessTokenExpiry)
                   .withIssuedAt(new Date())
                   .withNotBefore(new Date())
                   .sign(algorithm);

.net

      class Program
{
  static void Main(string[] args)
  {
      var rsaPrivateKey = "YOUR_PRIVATE_KEY";
      var privateKeyBytes = Base16Decoder(rsaPrivateKey);
      using var rsa = RSA.Create();
      rsa.ImportPkcs8PrivateKey(privateKeyBytes, out _);

      var signingCredentials = new SigningCredentials(new RsaSecurityKey(rsa), SecurityAlgorithms.RsaSha256)
      {
          CryptoProviderFactory = new CryptoProviderFactory { CacheSignatureProviders = false }
      };

      var now = DateTime.Now;

      var jwt = new JwtSecurityToken(
          issuer: "APP_SECRET",
          claims: new[] {

              new Claim("instCode", "INSTITUTION_CODE"),
              new Claim("userId", "USER_ID")
          },
          notBefore: now,
          expires: now.AddDays(1),// NO OF DAYS
          signingCredentials: signingCredentials
      );

      var token = new JwtSecurityTokenHandler().WriteToken(jwt);
      Console.WriteLine("Assertion: " + token);
  }

  public static byte[] Base16Decoder(String hex) {
      byte[] raw = new byte[hex.Length / 2];
      for (int i = 0; i < raw.Length; i++)
      {
          raw[i] = Convert.ToByte(hex.Substring(i * 2, 2), 16);
      }
      return raw;
  }
}
                  

python

from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import rsa
import jwt

import base64
import time

def create_token(private_key, app_key, institution):
  try:

      private_key_byte_arrary = base16Decoder(private_key)
     

      # Create RSA private key object from raw bytes
      private_key = serialization.load_der_private_key(private_key_byte_arrary, password=None)

      accessTokenExpiryTimeMs = 123123123234

      accessTokenExpiry = int(time.time() * 1000) + accessTokenExpiryTimeMs

      
      if isinstance(private_key, rsa.RSAPrivateKey):
          accessToken = jwt.encode(
              
              {
                "iss": app_key,
                "instCode": institution,
                "exp": 1803220460,
                "userId": "11111",
                "iat": 1680097337
              },
              private_key,
              'RS256'
          )
          return accessToken

  except Exception as e:
      print(e)

  return None


def base16Decoder(hex_string):
  bts = bytearray(len(hex_string) // 2)
  for i in range(len(bts)):
      bts[i] = int(hex_string[2*i:2*i+2], 16)
  return bytes(bts)

def base16Encoder(digestMsgByte):
  verifyMsg = ""
  for i in range(len(digestMsgByte)):
      hexChar = digestMsgByte[i] & 0xFF
      hexString = hex(hexChar)[2:]
      if len(hexString) == 1:
          verifyMsg += "0"
      verifyMsg += hexString
  return verifyMsg

def main():
  app_key = "app_key"
  app_secret = "app_secret"
  private_key = "private_key"
  institution = "institution_code"

  token = create_token(private_key, app_key, institution)


  print("assertion:", token)
  print("authorization: Basic", base64.b64encode((app_key + ":" + app_secret).encode()).decode())

if __name__ == '__main__':
  main()

JavaScript

const crypto = require('crypto');
const jwt = require('jsonwebtoken');

function createAssertion(privateKey, appKey, institution, userId) {
    try {
        const private_key_byte_arrary = base16Decoder(privateKey);

        const accessTokenExpiryTimeMs = 86400000; // 1 day
        const accessTokenExpiry = Date.now() + accessTokenExpiryTimeMs;

        // Create RSA private key object from raw bytes
        const private_key = crypto.createPrivateKey({ key: Buffer.from(private_key_byte_arrary), format: 'der', type: 'pkcs8' });

        const payload = {
            instCode: institution,
            exp: accessTokenExpiry,
            userId: userId
        };

        const options = {
            algorithm: 'RS256',
            issuer: appKey,
            allowInsecureKeySizes: true
        };

        const accessToken = jwt.sign(payload, private_key, options);

        return accessToken;
    } catch (e) {
        console.error(e);
        return null;
    }
}



function base16Decoder(hex_string) {
  const bts = new Uint8Array(hex_string.length / 2);
  for (let i = 0; i < bts.length; i++) {
    bts[i] = parseInt(hex_string.slice(i * 2, (i + 1) * 2), 16);
  }
  return bts;
}

function base16Encoder(digestMsgByte) {
  let verifyMsg = '';
  for (let i = 0; i < digestMsgByte.length; i++) {
    let hexChar = digestMsgByte[i] & 0xff;
    let hexString = hexChar.toString(16);
    if (hexString.length === 1) {
      verifyMsg += '0';
    }
    verifyMsg += hexString;
  }
  return verifyMsg;
}


function main() {
    const appKey = 'app_key';
    const institution = 'app_secret';
    const userId = 'SERVER001'
    const privateKey = 'private_key';

    const assertion = createAssertion(privateKey, appKey, institution, userId);

    console.log("assertion : "+assertion);
}

main();

Request

application/json

Body

assertion stringrequired

signed JWT token at client side using institution code and user id in the payload

Responses

200

OK

application/json

Schema

Schema

status stringrequired

Possible values: [SUCCESS, FAILED]

reason stringrequired
rejectCode integerrequired

Find error codes here

accessToken string
refreshToken string
accessTokenExpiresAt integer

UTC time

refreshTokenExpiresAt integer

UTC time

tokenType string

Example: bearer

Example (from schema)

{
  "status": "SUCCESS",
  "reason": "string",
  "rejectCode": 0,
  "accessToken": "string",
  "refreshToken": "string",
  "accessTokenExpiresAt": 0,
  "refreshTokenExpiresAt": 0,
  "tokenType": "bearer"
}

example

{
  "status": "SUCCESS",
  "reason": "auth token generation success",
  "rejectCode": 0,
  "accessToken": "O0AeyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyb2xlIjoiYnJva2VyIiwicHJvdmlkZXIiOiJvbXMiLCJpc3MiOiJHVE4iLCJpbnN0Q29kZSI6IlRSQURFX0FQSV9JTlNUX09ORSIsImV4cCI6MTcwMzg3MjUyNCwidXNlcklkIjoiMTExMTEiLCJpYXQiOjE3MDM4MzYyMjQsImp0aSI6Ijk4MGMwN2NlLWMxYTItNGE4MC04MjRjLTNmYzE4ZTAzODExOCJ9.V1RFsmb_NujX8axIyXnN3DqESpiw_fnGYmWg8W-ZV78",
  "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyb2xlIjoiYnJva2VyIiwicHJvdmlkZXIiOiJvbXMiLCJpc3MiOiJHVE4iLCJpbnN0Q29kZSI6IlRSQURFX0FQSV9JTlNUX09ORSIsImV4cCI6MTcwMzkwODUyNCwidXNlcklkIjoiMTExMTEiLCJpYXQiOjE3MDM4MzY1MjQsImp0aSI6IjY5NmVjZjBkLTFkNmYtNDQ2Yy1iOGE2LTkwNTdhZWVhODdmYSJ9.8blwnkQ-kFYyGoKpJJmsyjl2LdVsHA9dYnLNmUnkj88",
  "accessTokenExpiresAt": 1703872524416,
  "refreshTokenExpiresAt": 1703908524415,
  "tokenType": "bearer"
}

401

Unauthorized

application/json

Schema

Schema

timestamp string
status string
error string
message string
path string
rejectCode string

Example (from schema)

{
  "timestamp": "string",
  "status": "string",
  "error": "string",
  "message": "string",
  "path": "string",
  "rejectCode": "string"
}

Invalid Token

{
  "timestamp": "2023-12-28T09:51:50.682Z",
  "status": "401",
  "error": "Unauthorized",
  "message": "Invalid Token",
  "path": "/api/auth/token",
  "rejectCode": "1008"
}

Expired Token

{
  "timestamp": "2023-12-28T09:51:50.682Z",
  "status": "401",
  "error": "Unauthorized",
  "message": "Expired Token",
  "path": "/api/auth/token",
  "rejectCode": "1007"
}

Loading...