Authentication - App Token

This is the alternative feature for shared single sign-on (SSO) bearer token, You could use these two solutions at the same time. The app token authentication is a scalable solution for supporting distributed server environments. And more secure for the signing control and protection of the connection.

Before completing authentication, ensure that the GTR server authenticates incoming requests by verifying the application token in the X-Authorization header. To generate the application token, follow the steps below.

The test request sent is below:

curl --location --request GET 'https://platform.globaltravelrule.com/api/list \
-k --cert-type P12 --cert
./certificate.p12:'[MY_PASSWORD_OF_CERT]' \
--header 'Content-Type: application/json' \
--header 'X-Authorization: [AppToken]'

About to generate the App token, you should prepared these info:

Attribute Key Name	Type	Description	Example
secretKey	string	Get your secret key from the mTLS api_key.csv file.	8adba6ef063be8370fb9a7fb91d7498e905db8640442e1f5be6964
vaspCode	string	Get your vaspCode from the mTLS api_key.csv file.	f93_faj30ae3
secretToken	string	secretToken is not secretKey, please mind that this is generated by: sha512(secretKey+vaspCode)	5875058cd99d05d00d8c794b0e4b779f27f42992cf41639133effe28b8a5c109b8250f3e6c379c485e751b759378c6ded0360ac2c46c78106c879827df898e95
accessKey	string	Get your access key from mTLS api_key.csv file.	2DF9SDJ3RFA93HFA0F93HAB0S93F
algorithm	string	Please set it as hmac-sha512, it is the common algorithm type.	hmac-sha512
nonce	string	Random strings for nonce, uuid or random are all acceptable, please mind the encoding out of ASCII may cause the issue, please avoid this if possible.	03kadafd039hfa-2dasdf
timestamp	string	13 digits current timestamp	1701734400000
expires	int	The token will be expires in seconds	15 (15 sec is recommended)
verifyType	int	Please set as 1, it is the common verify type.	1

The process of hash the app token is:

AppToken = base64({
    "secretToken": "[SecretToken]",
    "accessKey": "[AccessKey]",
    "algorithm": "hmac-sha512",
    "nonce": "03kadafd039hfa-2dasdf", // random string or uuid is accepted
    "timestamp": "1701734400000", // unix - 13 digits
    "expires": 15, // 15 seconds
  "verifyType": 1 // fixed is 1
})

For the SecretToken, the process to generate is below, and please follow the sequence orders to permute the variable:

SecretToken = sha512([AccessKey] + "|" + sha512([SecretKey] + [VaspCode]) + "|" + [nonce] + "|" + [timestamp] + "|" + [expired_time] + "|" + [verify_type])

For example:

• AccessKey: 2DF9SDJ3RFA93HFA0F93HAB0S93F
• SecretKey: 8adba6ef063be8370fb9a7fb91d7498e905db8640442e1f5be6964
• VaspCode: f93_faj30ae3
• nonce: 03kadafd039hfa-2dasdf
• timestamp: 1701734400000
• expires: 15
• verifyType: 1 (Fixed)

The sha512([SecretKey]+[VaspCode]) will be:

5875058cd99d05d00d8c794b0e4b779f27f42992cf41639133effe28b8a5c109b8250f3e6c379c485e751b759378c6ded0360ac2c46c78106c879827df898e95

So the full payload will be:

SecretToken = sha512("2DF9SDJ3RFA93HFA0F93HAB0S93F|5875058cd99d05d00d8c794b0e4b779f27f42992cf41639133effe28b8a5c109b8250f3e6c379c485e751b759378c6ded0360ac2c46c78106c879827df898e95|03kadafd039hfa-2dasdf|1701734400000|15|1")

Which is:

SecretToken = 710c776f6048bd6aa30979b892a44046ea97f57eb4ba64eb985eb994446d66d408906715cfc51c365b05ed9eff74b71e202181a00dc16b1bfc0f75cbff316fa4

After the SecretToken has been well generated, we can complete to the AppToken template:

AppToken = base64({
    "secretToken": "710c776f6048bd6aa30979b892a44046ea97f57eb4ba64eb985eb994446d66d408906715cfc51c365b05ed9eff74b71e202181a00dc16b1bfc0f75cbff316fa4",
    "accessKey": "2DF9SDJ3RFA93HFA0F93HAB0S93F",
    "algorithm": "hmac-sha512",
    "nonce": "03kadafd039hfa-2dasdf",
    "timestamp": "1701734400000",
    "expires": 15,
    "verifyType": 1
})

Which is:

ewoJInNlY3JldFRva2VuIjogIjcxMGM3NzZmNjA0OGJkNmFhMzA5NzliODkyYTQ0MDQ2ZWE5N2Y1N2ViNGJhNjRlYjk4NWViOTk0NDQ2ZDY2ZDQwODkwNjcxNWNmYzUxYzM2NWIwNWVkOWVmZjc0YjcxZTIwMjE4MWEwMGRjMTZiMWJmYzBmNzVjYmZmMzE2ZmE0IiwKCSJhY2Nlc3NLZXkiOiAiMkRGOVNESjNSRkE5M0hGQTBGOTNIQUIwUzkzRiIsCgkiYWxnb3JpdGhtIjogImhtYWMtc2hhNTEyIiwKCSJub25jZSI6ICIwM2thZGFmZDAzOWhmYS0yZGFzZGYiLAoJInRpbWVzdGFtcCI6ICIxNzAxNzM0NDAwMDAwIiwKCSJleHBpcmVzIjogMTUsCiJ2ZXJpZnlUeXBlIjogMQp9

Now put these to your request payload, the example of request is below:

curl --location --request GET 'https://platform.globaltravelrule.com/api/list \
-k --cert-type P12 --cert
./certificate.p12:'[MY_PASSWORD_OF_CERT]' \
--header 'Content-Type: application/json' \
--header 'X-Authorization: ewoJInNlY3JldFRva2VuIjogIjcxMGM3NzZmNjA0OGJkNmFhMzA5NzliODkyYTQ0MDQ2ZWE5N2Y1N2ViNGJhNjRlYjk4NWViOTk0NDQ2ZDY2ZDQwODkwNjcxNWNmYzUxYzM2NWIwNWVkOWVmZjc0YjcxZTIwMjE4MWEwMGRjMTZiMWJmYzBmNzVjYmZmMzE2ZmE0IiwKCSJhY2Nlc3NLZXkiOiAiMkRGOVNESjNSRkE5M0hGQTBGOTNIQUIwUzkzRiIsCgkiYWxnb3JpdGhtIjogImhtYWMtc2hhNTEyIiwKCSJub25jZSI6ICIwM2thZGFmZDAzOWhmYS0yZGFzZGYiLAoJInRpbWVzdGFtcCI6ICIxNzAxNzM0NDAwMDAwIiwKCSJleHBpcmVzIjogMTUsCiJ2ZXJpZnlUeXBlIjogMQp9'

Now you don’t need to login, use the generate token method to apply to all of the api invoke, and start to use the GTR api.