In Maya, Bearer Authentication is used in the Maya Mini App Solution, specifically for Profile Sharing and Payments only.

Overview

Bearer Authentication (also known as Token Authentication) is a secure way to verify your identity when accessing API endpoints. Instead of using API keys, you use a Bearer Token—a temporary access token generated via OAuth 2.0.

What is OAuth 2.0?

OAuth 2.0 (Open Authorization) is an industry-standard framework for securing access to APIs and user data. If you are new to OAuth 2.0, check the OAuth documentation for more details.

There are multiple authorization flows in OAuth 2.0, but certain Maya APIs use the Client Credentials Grant to generate the Bearer Token.

What is the Client Credentials Grant?

The Client Credentials Grant is an authorization flow used when an application (such as a backend service) needs to authenticate itself to access resources rather than acting on behalf of a user. It is commonly used for:

Server-to-server communication (e.g., internal API calls)
Machine-to-machine authentication (e.g., microservices)

Client Credentials Grant generates a Bearer Token, an access token that allows the application (client) to authenticate itself when calling an API. Think of it as an API-only authentication method where the client (e.g., a backend service) gets a temporary token to access protected resources.

Bearer Token Expiry in Maya

In Maya, the Bearer Token is valid for 3600 seconds only.

Your Access to Maya Connect

In Maya, you will be granted access to Maya Connect, the OAuth service in Maya, for the OAuth 2.0 Client Credentials Grant implementation to generate your Bearer Token.

Acquiring Your API Credentials for Client Credentials Grant

Maya Connect will require that you go through onboarding first. During onboarding, your Maya Relationship Manager will ask you to submit the following:

The email address of your nominated key recipient
The public GPG key of your nominated key recipient. If you are unfamiliar with GPG, see the GNUPG document and start importing a public GPG key.

After successful onboarding, Maya will give you a client_id and a client_secret that you will use when your application interacts with the service. These credentials will be stored in an encrypted file using the public GPG you submitted during onboarding. The encrypted file will be sent to your nominated key recipient via email. Refer to the GNUPG document to start decrypting your file.

Keep in Mind

Maya has two (2) environments, Sandbox and Production, each with distinct keys or credentials. See the API Environment to familiarize the API environments of Maya.

API credentials are specific to the Maya solution you will be using

Storing Your API Credentials

API Credentials will be used to authenticate your application, so save them in a secure location. Misuse or mishandling of tokens or keys within the jurisdiction of the Partner could entail risks and vulnerability of transactions.

If your API keys are lost or breached, delete the old API keys and request to generate new ones in the same environment.

Generating Your Bearer Token

1. Prepare Your API Credentials

Now that you have acquired your API credentials, you may now start using them to obtain your Bearer Token via Maya Connect.

Maya Connect API uses Basic Authentication for token requests. This means you send your client_id and client_secret encoded in Base64 with each request.

Basic Authentication in Maya Connect API

Format the credentials. Use the client_id as the username, then put a colon (':') after it. Then, put the client_secret as the password (after the colon).
Convert to Base64. The next step is to encode the formatted string from Step 1 using Base64. You can use an online Base64 encoder or do it in code (e.g., in Python: base64.b64encode(credentials.encode()).decode()).
Add the Authorization header. In your Maya Connect API request, include an Authorization header. The value should be "Basic " followed by the Base64-encoded string from Step 2.

Sample Codes:

import base64

username = "client_id"
password = "client_secret"
credentials = f"{username}:{password}"
encoded_credentials = base64.b64encode(credentials.encode()).decode()

print("Basic " + encoded_credentials)

const username = "client_id";
const password = "client_secret";
const credentials = `${username}:${password}`;
const encodedCredentials = btoa(credentials);

console.log("Basic " + encodedCredentials);

2. Request a Bearer Token

After preparing the Authorization header, build the request by following the correct API specification, then send the valid request to the Create Access Token endpoint.

For every successful call, the API returns a fresh Bearer Token (access_token), invalidating the previous ones.

Refer to the Code Recipe below to guide you in building the request:

📖

Generate Client Credentials Token

Open Recipe

Using the Bearer Token for Bearer Authentication

Store your Bearer Token securely for use in API requests. If your token is breached, request a new token to invalidate the old one.

Now that you have acquired your Bearer Token, you may now start using it to verify your identity as an authorized entity accessing the Maya endpoints that require Bearer Authentication. API Authentication is performed during the transaction requests.

Use the Bearer Token in the Authorization header to authenticate your API requests to specific Maya solutions.

How to Use Bearer Authentication

Add the Authorization header to the API request.
Set the value to "Bearer " followed by the Bearer Token.

Authorization: Bearer your_generated_token

Handling the Expired Bearer Token

In Maya, the Bearer Token is valid for 3600 seconds only.

When the Bearer Token (access_token) expires, your application should send a new request to the Create Access Token endpoint to obtain a fresh token.

Handling of OAuth 2.0 Errors

For the list of errors and how they can be handled, please refer to the OAuth 2.0 Authentication Errors.

Next Steps

Aside from the Authorization header, there are required fields that you must include in the API request. Be sure to review the API documentation of the solution you are integrating with for the correct specifications.

Bearer Authentication