About API authentication

Mazooma APIs use the industry-standard OAuth 2.0 framework to authenticate and authorize applications to make API calls. Together, the client ID, client secret, and app ID identify the client and which functionalities it can access.

When the authentication and authorization process is complete, the Merchant system receives an access token, which needs to be included in the header of every API call.

Before you can authenticate, you must obtain a client ID, client secret, and an app ID from the Mazooma Merchant Integration team. You’ll need these credentials to request an access token for the staging environment. After your system integration is complete, you’ll receive separate credentials to use in the production environment.

Getting an access token

Request

Access tokens are retrieved via the OAuth Client Credentials flow, which is used for server-to-server authentication. With the client credentials flow, the Merchant system must securely store its client ID and client secret, and pass them to the Mazooma authentication server in exchange for an access token.

In addition to the client ID and client secret, the grant type, which specifies that we’re using the client credentials flow, and content type is passed in the header of a request sent to the authentication token URL:

POST https://staging.mazoomagateway.com/register/oauth/token

Parameter Description
grant_type This is always submitted as client_credentials.
client_id The client ID assigned by Mazooma.
client_secret The client secret assigned by Mazooma.
content-type For access token requests, this is application/x-www-form-urlencoded.
Example request
curl --request POST \
--url "https://staging.mazoomagateway.com/register/oauth/token" \
--data "grant_type=client_credentials&client_id=<assigned client ID>&client_secret=<assigned client secret>" \ 
-H "Content-Type: application/x-www-form-urlencoded"

Response

Parameter Description
access_token The bearer token retrieved from the authorization server
expires_in The time, in seconds, until the token expires
token_type This is always Bearer
scope The scope granted to the access token
Example response
{
  "access_token": "<token>",
  "expires_in": "<expires in seconds>",
  "token_type": "Bearer",
  "scope": "report transaction"
}

Using an access token

Mazooma uses Bearer authentication, which uses security tokens called bearer tokens. The bearer token is one of the parameters that must be included in the header of each API call.

Headers

All transaction and reporting API calls require the following headers:

  • x-pgw-client-id: client_id
  • x-pgw-app-id: app_id
  • Authorization: Bearer token
  • Content-Type: application/json
Example header
{
  "x-pgw-client-id": "34ff3d8e-4911-11ea-b77f-2e728ce88125",
  "x-pgw-app-id": "57758fee-4911-11ea-b77f-2e728ce88125",
  "Authorization": "Bearer a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a",
  "Content-Type": "application/json"
}