API Keys and Authentication

Following the previous chapter Get API Key and mTLS Certificates, after downloading the API Keys file, you'll find a file called api_key.csv in the zip file.

Examine the api_key.csv file to find the following information:

Field Name	Description
vaspCode	vaspCode identifier for API Login
accessKey	API Access Key for API Login
secretKey	API Secret Key for API Login. Before login, apply `sha512(secretKey)` to create `signedSecretKey` for login
curvePublicKey	(Only available in test) GTR on-behalf to generate the ed25519 key-pair public key, please generate by your self if you are in production propose
curvePrivateKey	(Only available in test) GTR on-behalf to generate the ed25519 key-pair private key, please generate by your self if you are in production propose

There are two ways to implement token generation for GTR API requests:

Single Sign-On (Good for debug and development)
App Token (*Recommended for production)

Single Sign-On (SSO)

Before completing authentication, note that the GTR server authenticates incoming requests by verifying the bearer token in the Authorization header. Follow these steps to generate the bearer token:

How to build authentication payload

Use the information from your api_key.csv file to fill the following JSON format:

{
  "vaspCode": "[vaspCode]",
  "accessKey": "[accessKey]",
  "signedSecretKey": "sha512([secretKey])",
  "expireInMinutes": 86400 // leave it unset live for lifetime
}

For example:

{
  "vaspCode": "f93_faj30ae3",
  "accessKey": "2DF9SDJ3RFA93HFA0F93HAB0S93F",
  "signedSecretKey": "6bbb4d21bdb8a0720f9b9850b96b1110c3bcab725d4e829722581461d4ee3cd8f9431e4f4d90c739328d03a04f6280067a1e30de258a85755f214d2942d42b21",
  "expireInMinutes": 86400
}

signedSecretKey is the SHA-512 hash of your secret_key
sha512 is a pure hash function, NOT using HMAC
expireInMinutes is optional and expires the token after 86,400 minutes (60 days). If unset, the token won't expire except when you logout or change the API key

Referring to the .csv file, assume the example secret_key is:

DFSD0JFN43SGNDSPIAN30IHSIDFN0SAR3BNFA0ISFNBI0N3RNFWE0F

After applying SHA-512 hashing, the result will be:

6bbb4d21bdb8a0720f9b9850b96b1110c3bcab725d4e829722581461d4ee3cd8f9431e4f4d90c739328d03a04f6280067a1e30de258a85755f214d2942d42b21

Send the request to the GTR server to receive a login response.

Here's a shell example script for login. Implement the login method in your service program:

curl --location --request POST 'https://uat-platform.globaltravelrule.com/api/login' \
-k --cert-type P12 --cert ./certificate.p12:'[MY_PASSWORD_OF_CERT]' \
--header 'Content-Type: application/json' \
--data-raw '{
    "vaspCode": "f93_faj30ae3",
    "accessKey": "2DF9SDJ3RFA93HFA0F93HAB0S93F",
    "signedSecretKey": "6bbb4d21bdb8a0720f9b9850b96b1110c3bcab725d4e829722581461d4ee3cd8f9431e4f4d90c739328d03a04f6280067a1e30de258a85755f214d2942d42b21"
}'

The endpoint uat-platform.globaltravelrule.com is for UAT (Test Environment). Change to platform.globaltravelrule.com for Production Environment. NOTE: API Keys (SecretKey, AccessKey, etc.) differ between environments, so Test Environment API Keys CANNOT BE USED IN PRODUCTION.
You are required to use the certificate.p12 file in conjunction with your personal password when sending a request to the GTR login endpoint.
[MY_PASSWORD_OF_CERT] is the password that set up from instructions in the Get API Key & mTLS Certificates chapter. It will be used to secure the private key and the signed certificate pair file (.p12).

Once it successful to execute login, you will receive a response similar to the following example:

{
  "data": {
    "jwt": "eyJWTTokenblablabla",
    "vaspCode": "f93_faj30ae3"
  },
  "verifyMessage": "success",
  "verifyStatus": "100000",
  "success": true
}

The data.jwt token will be the Bearer Token that you use to send any request to the GTR server.

About API access token

To access the API to the GTR server, the JWT Bearer token issued after successful login needs to be carried.

Please put the JWT Bearer token to the header of your HTTP request.

Header Key: Authorization
Value: Bearer + space + JWT_TOKEN

Here is an example of how you will later use the JWT to send the request to check the current login status:

curl --silent --location --request GET "https://platform.globaltravelrule.com/api/status" \
    -k --cert-type P12 --cert ./certificate.p12:'[MY_PASSWORD_OF_CERT]' \
    --insecure \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer eyJWTTokenblablabla" \
    --header "Connection: keep-alive"

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/vasp/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
vaspSecretKeyHash	string	vaspSecretKeyHash 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, and must use UTC+0 timezone.	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] + "|" + [vaspSecretKeyHash] + "|" + [nonce] + "|" + [timestamp] + "|" + [expired_time] + "|" + [verify_type])

vaspSecretKeyHash is: sha512([secretKey] + [vaspCode])

For example:

AccessKey: 2DF9SDJ3RFA93HFA0F93HAB0S93F
SecretKey: 8adba6ef063be8370fb9a7fb91d7498e905db8640442e1f5be6964
VaspCode: f93_faj30ae3
nonce: 03kadafd039hfa-2dasdf
timestamp: 1701734400000
expires: 15 (Second)
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.

API Keys and Authentication

How to build authentication payload​

Get access token with login API​

About API access token​

App Token

How to build authentication payload

Get access token with login API

About API access token