Create an Access Token

An access token is a unique, single-use key used to access API actions for a limited time and is required for every request to create, edit, or read resources. For example, in order to send a transaction, you first need to create a token to access our API.

The actions you'll be able to perform (allowable actions) are based on capabilities you were assigned when you registered for your Developer Portal account.

This guide will walk you through the following steps to create an access token, including:

• Obtaining your app credentials
• Creating a random nonce value
• Calculating a secret key
• Calling the endpoint
• Receiving a response

You’ll also find information on how an access token differs from other token types.

An access token is used only for authentication. It's sometimes mistaken for a payment token, which is another type of token used to substitute sensitive card data in a transaction. While a payment token can be either single-use or multi-use, an access token is a single-use token only. There are also some functional differences between payment tokens and access tokens.

• Duration – Limits how long it is valid for (timeout value)
• Permissions – Restricts the functionality (required for hosted integrations)

Token Duration and Token Permissions can be limited for security purposes. The shorter the duration of a token, the less time it is able to be abused, and the fewer permissions available for a token to access, the less likely bad actors can repurpose it for exploits. Some integration types and features, such as our hosted features, require single permission tokens to avoid this exact problem on the clearweb (aka the surface web).

Before you can use the steps in this guide to create an access token, you first have do the following:

• Get registered
• Create an app (generate keys)

Your app credentials are the app_id and app_key. Your app credentials for testing in Sandbox are located on your account page (to learn how to create them, see Register / Create an App). For Production credentials, check with your account manager.

For example:

app_id = "MN500Q8lk5jp0rEmB5LGvTo27gdQgZln"
app_key = "QtOSeNmh3DY6AuMO"

A random nonce is a unique string used to calculate the secret key, which you'll do in the next step. The nonce value must be unique. A timestamp makes a good nonce value because the time changes every time an access token is run, which makes it a unique value.

For example:

nonce="2029-03-14T13:24:10.832Z"

For security reasons, you should never send your app_key in a request. That’s why we use encryption to make it secret. The secret key consists of a SHA512 hash of the nonce concatenated with the app_key.

For example:

// secret = SHA512(nonce + app_key)
secret = SHA512(2029-03-14T13:24:10.832ZQtOSeNmh3DY6AuMO) 

Now it’s time to send the values from the previous steps to the Access Token endpoint.

Sample request

curl -v -X POST https://apis.globalpay.com/ucp/accesstoken 
  -H "Content-type: application/json" 
  -H "X-GP-Version: 2021-03-22" 
  -d '
      {
       app_id="<APP_ID>"
       nonce="<NONCE>",
       secret="<SECRET>",
       grant_type="client_credentials"
       }
'

When you call the endpoint, you'll receive the token response and its permissions, which you can now use in the Authorization header field in subsequent API requests.

Sample response

{
 "token": "qdYUdzfZfigqTppQOHVwrbJwLlNd",
“Type”: “Bearer”,
 "scope": {
    "merchant_id": "MER_8cc2638c8a14453fa98e08ad51511a1a",
    "merchant_name": "GPQA_IPP_CERT",
    "accounts": [
      {
        "id": "TRA_34b9806b35bd4012bd23206a00abc1a1",
        "name": "GP API",
        "permissions": [
          "BAT_PUT_Close",
          "TRN_POST_Adjustment",
          "TRN_POST_Authorize",
          "TRN_POST_Capture",
          "TRN_POST_Force",
          "TRN_POST_Initiate",
          "TRN_POST_Reauthorize",
          "TRN_POST_Refund",
          "TRN_POST_Refund_Standalone",
          "TRN_POST_Reverse",
          "TRN_POST_Verify"
        ]
      }
    ]
  },
  "app_id": "MN500Q8lk5jp0rEmB5LGvTo27gdQgZln",
  "app_name": "My app name",
  "date_created": "2019-03-20T10:42:23.527Z",
  "seconds_to_expire": "86399",
  "email": "dev.mcdev@example.com"
}

The two most common error messages errors users experience when trying to pass an access token in a request are:

• Invalid Access Token – This most often occurs when a token request is rejected, but your website or application attempts a transaction anyway.
• Access Token Expired – This occurs if a token is used after its timeout value has passed (interval_to_expire or seconds_to_expire fields).

If you run into issues passing a token, the following questions will help you troubleshoot:

1. Are the app_id and app_key you’re using correct?
2. Was the secret key calculated correctly and properly entered in the field?
3. Are other mandatory fields you included in the request correct (for example, grant_type)?
4. Do you have the right account permissions for your request? If you’re not sure, check with your account manager.

Now that you have your test app credentials and an access token, it's time to start building your integration.