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. |
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 |
{
"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
{
"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"
}