Before you start

Before you proceed with Issuing a JWT Token, make sure that you have completed the following step:

• Creating a Service account

What is a JWT token

A JWT token is a compact, URL-safe means of representing claims to be transferred between two parties as a JSON object. In the context of our platform's API, it serves as a digital signature for authentication that verifies your identity and grants you access to protected endpoints.

Please note that JWT token has a validity period: The access token (access_token) is valid for 3600 seconds (1 hour).

Along with the access token, a refresh_token is issued, which can be used to obtain a new access token without re-authenticating.

How to issue a JWT token

To obtain a JWT token, use the Issue a Service Account Token method and perform the steps below:

1. Have your service account credentials: Ensure you have your account_id and public_key. The public_key is obtained by encoding the content of your public-key.pem file using Base64 encoding.
2. Send a POST request to the Authentication endpoint:
   • Endpoint:\
     

   POST https://secure.sandbox.paymentsgate.io/auth/token

   • Headers:
     • Content-Type: application/json
   • Request body:\
     

     {
       "account_id": "YOUR_ACCOUNT_ID",
       "public_key": "BASE64_ENCODED_PUBLIC_KEY"
     }

     Replace YOUR_ACCOUNT_ID with your actual service account ID and BASE64_ENCODED_PUBLIC_KEY with your Base64-encoded public key.
   • Example request:\
     

     curl --request POST \
       --url 'https://secure.sandbox.paymentsgate.io/auth/token' \
       --header 'Content-Type: application/json' \
       --data '{
         "account_id": "00000000-0000-4000-0000-000000000000",
         "public_key": "LS0tLS1CRUdJTiBQV....."
       }'

   • Successful response:
     If the credentials are valid, you'll receive a response containing your access_token, refresh_token, and expires_in (token validity period in seconds).

     {
       "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
       "refresh_token": "8xLOxBatCN8fDrMHtkX1uDgeHxWxhoJDl...",
       "expires_in": 3600
     }

     • access_token: Use this token in the Authorization header for subsequent API requests.
     • refresh_token: Use this to obtain a new access token when the current one expires.
     • expires_in: Indicates the number of seconds the access token is valid (e.g., 3600 seconds).
3. Use the Access token:
   Include the access_token in the Authorization header of your API requests:

   Authorization: Bearer YOUR_ACCESS_TOKEN

For more detail, please see the Issue a Service Account Token API method description.

Generating an RSA key pair

What is an RSA key pair

An RSA key pair consists of a private key (used to sign or decrypt data) and a public key (used to verify signatures or encrypt data). In the context of our platform's API, RSA keys can be used to securely authenticate and sign requests, ensuring data integrity and trust between parties.

📘

Note

Soon, users will be able to either enable or disable RSA signature functionality. Please stay tuned for the upcoming product updates.

How to generate an RSA key pair

Below are instructions for generating an RSA key pair on different operating systems using OpenSSL.

Linux and macOS

• Check if OpenSSL is installed: OpenSSL is commonly pre-installed on many Linux and macOS systems. To verify your OpenSSL installation:

openssl version

• If OpenSSL is not installed (or you need an update), you can install it with your system’s package manager.

Ubuntu/Debian example:

sudo apt update && sudo apt install openssl

macOS example (via Homebrew):

brew install openssl

• Generate a private key:
  Use the following command to generate a 2048-bit RSA private key:

  openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

• Generate a public key:
  After generating the private key, create the corresponding public key:

  openssl rsa -in private_key.pem -pubout -out public_key.pem

  To verify that both keys exist in the current folder:

  ls | grep '_key.pem'

Windows (PowerShell)

• Install and configure OpenSSL:
  • Download OpenSSL from the official website.
  • Install OpenSSL on your system.
  • Add the path to the OpenSSL executables (e.g., C:\OpenSSL-Win64\bin) to your system’s PATH environment variable.
• Generate RSA keys:
  Open PowerShell and run commands similar to those on Linux/macOS:

  openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
  openssl rsa -in private_key.pem -pubout -out public_key.pem

  Verifying Your RSA Keys

  To ensure the keys have been generated correctly, you can inspect their contents:
• Private key:

  openssl rsa -in private_key.pem -text -noout

• Public key:

  openssl rsa -in public_key.pem -pubin -text -noout

If these commands display valid RSA key information, you have successfully generated and verified your RSA key pair.