API Reference
Log In
API Reference

Authentication Guide

In This Section

In the Authentication section of the borderless™ documentation you will find:

  • Definitions for Secret Key, Issuer ID, JWT Token, and iat
  • How to Authenticate borderless™ API Calls
  • How to Generate Your JWT Token via API
  • How to Generate Your JWT Token via Dashboard
    1. Generate Your JWT Token via Generator Button
    2. Generate Your JWT Token Manually
  • How to Authenticate Partner Requests for a Child Account

Definitions

TermDefinition
Issuer IDAn Issuer ID is a 25 character alphanumeric string that is unique to your borderless™ Account and can be revealed in the Issuer ID column on the "Tokens" tab of your Developer Dashboard. An example would look like this:
al2gyjp2bqqkm1598ekv9etfd
Secret KeyA Secret Key is a 36 character string that is unique to your borderless™ Account and is generated from the "Tokens" tab of your Developer Dashboard. It is distinct from the JWT. An example would look like this: 42f1828e-c705-11ec-9d64-0242ac120002
Partner KeyA Secret Key is a 36 character string that is unique to a Partner Account.
JWT TokenA JWT Token is an open standard that defines a compact and self-contained way for securely transmitting information. A JWT Token is made of 3 parts: the Header, the Payload and the Signature.
Client-IdA Client-Id is a unique identifier of a Child Account. A Client-Id must be provided in the header for Authentication. If a Client-Id is not provided in the header, all calls will be specific to the Partner Account.
iatIssued At Time or iat is a time stamp that indicates JWT Token lifespan. This is represented in Unix time which you can read about here. The iat will expire after 15 minutes.

How To Authenticate borderless™ API Calls

borderless™ API Calls must be signed with your JWT Token for authentication. To use your JWT Token, enter it after “--header 'Authentication: Bearer” in an HTTP request or paste it into the "Bearer" field in the borderless™ Sandbox UI.

👍

Pro Tip

This token is valid for 15 minutes and needs to be regenerated after expiry.

How To Generate Your JWT Token via API

You can generate JWT token using our Authentication Endpoint.

How To Generate Your JWT Token via Dashboard

Generate Your JWT Token via Generator Button

A JWT Token Generator Button can be found in your Developer Dashboard. Click the "Generate Token" button and a JWT Token will automatically be created. This Token can be copied to your clipboard where you can then place that as the Bearer header in HTTP requests to Authenticate your API Calls.

Generate Your JWT Token Manually

To manually generate your JWT Token, follow these steps:

  • Step 1: Go To Developer Dashboard

    In your borderless™ Account, navigate to the Developer Dashboard. You will see a tab marked "Tokens."

  • Step 2: Go To "Tokens" Tab

    Within the Developer Dashboard navigate to the "Tokens" tab. If this is your first time issuing a JWT Token in your borderless™ Account, the "Tokens" table will be empty.

  • Step 3: Generate Secret Key

    In the top right hand corner of the "Tokens" tab of your Developer Dashboard (below "Documentation") you will find a button labeled "Generate Key." Click this button to generate your Secret Key. Keep your Secret Key safe and DO NOT share it with anyone else. It is a unique identifier for your borderless™ Account and will only be revealed to you once. The Secret Key will be used as part of the authentication process.

  • Step 4: Reveal Issuer ID

    Once you have generated your Secret Key a table will appear in your "Tokens" tab. Under the Issuer ID column in the table you will see the option to "reveal" your Issuer ID. Click "reveal" to reveal your Issuer ID. Keep your Issuer ID safe and DO NOT share it with anyone else. The Issuer ID is unique to your borderless™ Account and will be used as part of the authentication process.

  • Step 5 (Optional): Ask for your Partner Key

    Partner keys are secret and given upon Partner Account approval.

  • Step 6: Manually Generate JWT Token

    Follow these steps to manually generate a JWT Token.

    • Go to: https://jwt.io/.

    • In the “Payload” field you will need to provide your Issuer ID and iat (“Issued At Time"). The payload should look something like this: 

{
  “issuer”: al2gyjp2bqqkm1598ekv9etfd
  “iat”: 1651158899
}

{
  “issuer”: al2gyjp2bqqkm1598ekv9etfd
  “partnerKey”: dfv5d4fv545fv4-dfv54-fv55-df5v454v4v
  “iat”: 1651158899
}
  • In the “Verify Signature” field you will need to provide your Secret Key.

Congratulations! The generated string under the "Encoded" section is your JWT Token that will be used to Authenticate your borderless™ API calls.

👍

Pro Tip

Authenticating Requests as a Partner for a Child Account

  • Provide Partner Key when generating token either via API using Authentication Endpoint or manually generating token.

❗️

Client-id Header Value

  • Provide Client-Id to every request's header (except Authentication Endpoint) to have access to your Child accounts.
  • To use Client-Id correctly, enter it in “--header 'Client-Id: {Client Id of Your Child account}” in an HTTP request.