Skip to main content
Search

Get API Key & mTLS Certificates

About

To obtain the API Key, GTR requires customers to submit their certificate request. This process provides two different components:

When you submit the Certificate Request, you will receive:

  1. Signed Certificate Files for mTLS Connection
  2. API Key for login and API Usage

The Certificate Request is represented in a file called .csr. The generation method is described in the section below.

mTLS (Mutual Transport Layer Security)

GTR employs mTLS to secure client requests to the API Server. This requires both parties to verify each other's certificates. To obtain your certificate, generate the Certificate Signing Request (CSR) on your local computer, upload it to GTR, and obtain the signed certificate.

API Key

To access the GTR API Server, generate the token using the API Key. We combine the mTLS certificate and API Secret Key into a single compressed file. After submitting your CSR and creating an API key, download this file, extract it, and store it securely in your vault.

Create a Certificate Request File on your computer (CSR)

We use your Certificate Signing Request (CSR) file to create the signature for GTR's HTTP request public key. The CSR describes your organization information for identification and is signed with your private key. You only need to provide the CSR to GTR to receive the public certificate, then use your paired private key for decryption. GTR never handles your private key, ensuring security.

Before creating an API Key, generate a Certificate Signing Request (CSR). Ensure OpenSSL is installed in your environment. Generate your CSR using the shell commands below. (After executing the command in the terminal, it will enter interactive mode. Answer according to your actual situation to complete file generation.)

openssl req -new -newkey rsa:4096 -nodes -keyout PRIVATE.key -out CSR.csr

For subject fields, provide the following information: 'C' for Country code, 'ST' for State, 'L' for Location, 'O' for Organization, and 'OU' for Organizational Unit. Ensure these fields are correctly populated and applicable to your company. For the 'CN' field (Common Name), input your domain name (e.g., 'sub.example.com'). The 'CN' identifies the domain where you enable the callback service, so confirm the domain maps to your callback server.

When completing subject fields, provide accurate information that aligns with your company's details:

  • 'C' stands for Country code. (Location / Country with 2-alphabet)
  • 'ST' represents the State. (Location / State)
  • 'L' is for the Location. (Location / City)
  • 'O' denotes the Organization. (Your organization name: Company Name)
  • 'OU' stands for Organizational Unit. (Your business unit: Department Name, For Example: Compliance)
  • 'CN' stands for Common Name. (Your domain name in lower-case, *For Example: example.com)

In the 'CN' field (Common Name), input your domain name (e.g., 'sub.example.com'). The 'CN' field identifies the domain where the callback service is activated, so verify the domain is correctly mapped to your callback server.

After completing these procedures, you will have generated two important elements: a private key ('PRIVATE.key') and a CSR ('CSR.csr'). The 'CSR.csr' file is essential for the next step.

Click the 'Create API Key' button. Attach the CSR, enter your domain name, and specify the client-truststore format before clicking 'Next'. This generates an access key, security key, and public certificate for your server ('certificate.pem'). Follow the on-screen prompts to proceed.

To generate a CSR with prefilled parameters, use the following command:

openssl req -new -newkey rsa:4096 -nodes -keyout PRIVATE.key -out CSR.csr -subj "/C=US/ST=California/L=San Francisco/O=OrganizationName/OU=IT Department/CN=[Your Domain Name]/emailAddress=contact@example.com"

To Get One Key

Here are the steps to create an API Key and mTLS certificates:

Visit the website: https://www.globaltravelrule.com. Navigate to: [My Account] -> [API Info] in the [API Key (Security Credential)] section. Click on [Create API Key].

Before accessing the verify server, you need mTLS connection and access/secret keys. Store these keys securely in a vault, allowing developers to retrieve access tokens from the vault. Ensure the HTTP client uses mTLS connection, meaning each connection includes the client certificate public key to the GTR service. (You must have private/public keys to send requests using the client certificate.)

Upon successful completion, you can download the key_and_certificate.zip file.

API key generation by the GTR server may take some time. Once generated, the new API key downloads automatically to your system.

If the API key doesn't download automatically, manually download it by clicking the "Download Key" button. Store your API keys securely. Each company can create only one access key every 24 hours. The access key and secret key generation follows predetermined rules:

Access Key: This is created by a randomized string adhering to the pattern ^[A-Z1-9]{64}$. Salt: This is a randomly generated string following the pattern ^[A-Z1-9]{16}$. Secret Key: Similar to the others, the secret key is a randomized string that follows the pattern ^[A-Z1-9]{256}$. Each account can have only one API key at a time. When a new API key is generated, the previous access key and secret key are immediately invalidated. Keep a record of the new API key, as the old one becomes obsolete.

Submit the CSR and Download Key Files​

After obtaining your signed certificate from the GTR website, access the contents of the key_and_certificate.zip file. When extracted, it contains the following three components:

key_and_certificate.zip
├── api_key.csv
├── certificate.pem
└── client-truststore.pem

key_and_certificate.zip: This file contains the mTLS certificate for any HTTPS request sent to the GTR server, including login procedures.

client-truststore.pem: This file is the client-trust Certificate Authority (CA) bundle, providing the whitelist client certificate. You may need to use this certificate to verify incoming requests from the GTR server.

Important: Do NOT use this file to send requests. This certificate is exclusively for receiving GTR callbacks to your server.

certificate.pem: This file houses the HTTPS certificate that is deployed by the business service when it initiates HTTPS requests to the GTR API.

Note: This file does not require a password. If a password prompt appears, leave the field empty.

Note: See the following steps for instructions on using this file to send an mTLS request.

Note: Please mind that the Test Environment Certificate and Private Key is not shared, change the certificate to Production one if you are in production propose.

api_key.csv: This document stores the access_key and secret_key.

Make key pair format - create .p12 or .jks for your server

There are several scenarios for using mTLS certificates in different formats:

Directly usage of certificate.pem and private.key​

This method involves starting your server with these keys directly. However, it's important to note that the private key is not password-protected, which could pose a security risk.

PEM to P12​

It is possible to combine the certificate.pem and your PRIVATE.key to one .p12 key store with your password lock, this format is suitable for java server application, if you like to convert to .p12, please use the command:

openssl pkcs12 -export -out server.p12 -inkey [PRIVATE_KEY_FILE_NAME].pem -in [CERTIFICATE_PUBLIC_KEY_FILE_NAME].pem -passout pass:[YOUR_PASSWORD]

PKCS12 - New​

To consolidate your private key and signed certificate into a .p12 file, follow the guidelines outlined below:

openssl pkcs12 -export -out certificate.p12 -inkey PRIVATE.key -in certificate.pem -passout pass:[YOUR PASSWORD OF CERTIFICATE]

Following these instructions accurately ensures the preservation and protection of your sensitive data, ultimately fostering an environment of secure and encrypted communication with the GTR server.

With the successful acquisition of the .p12 format certificate, you are now well-equipped. Please proceed to the section titled 'Prerequisites' to understand the process behind making a login request.

PKCS12 Legacy Java​

Using a legacy version of Java, specifically versions earlier than 8u301 or 11.0.1, may not allow for the direct use of the openssl command provided above to run your server. This limitation arises because the openssl command uses the PBE2 cipher, which is not handled correctly by the mentioned versions of Java.

Please refer to the following commend:

openssl pkcs12 -export -out certificate.p12 -inkey PRIVATE.key -in certificate.pem -passout pass:[YOUR PASSWORD OF CERTIFICATE] -legacy

JKS​

To bind your private key and signed certificate into a .jks (Java KeyStore) file, follow these specific steps:

openssl pkcs12 -export -in certificate.pem -inkey PRIVATE.key -out keystore.p12 -name gtr_keypair -passout pass:[YOUR PASSWORD OF CERTIFICATE]
keytool -importkeystore -destkeystore keystore.jks -srckeystore keystore.p12 -srcstoretype PKCS12 -alias gtr_keypair -deststorepass [YOUR PASSWORD OF CERTIFICATE]  -srcstorepass [YOUR PASSWORD OF CERTIFICATE]

Upon the successful execution of these instructions, you will have the 'certificate.jks' file in your possession.

The .jks file format is proprietary to the Java platform. If you're employing a different programming language, for instance, Python, you will need to transform the file format into PEM. Please refer to Appendix I for a detailed step-by-step guide on how to accomplish this file format conversion to PEM and to effectively establish a mTLS server.

Make HTTP Request with Certificate

Using .pem and .key to initiate cURL request​


curl  --location --request GET "https://uat-platform.globaltravelrule.com/api/network/test/check" --cert-type PEM --cert ./certificate.pem --key ./private.key

Using .p12 to initiate cURL request​

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

certficate.p12 have to compress by your self by using the command provide above section, using it to merge the certificate.pem and your PRIVATE.key with customize password to lock it:

openssl pkcs12 -export -out certificate.p12 -inkey PRIVATE.key -in certificate.pem -passout pass:[YOUR_PASSWORD_OF_CERT]