oAuth 2.0 Authentication

Note the following when generating or requesting your API Keys or Credentials:

  • Maya has two (2) environments, Sandbox and Production, each with distinct keys or credentials. Refer here for more details.
  • API credentials are specific to the Maya solution you will be using.

Acquiring your API Credentials for Maya Connect

During onboarding, your Maya Relationship Manager will ask you to nominate a key recipient and provide their public GPG key and email address. Your Maya Relationship Manager will assist you with the onboarding.

Once onboarded, the API keys or credentials will be sent to your nominated key recipient. These credentials will be stored in an encrypted file using the submitted public GPG key. Refer to the GPG guide for instructions on decrypting the file.

Authenticate Requests using Maya Connect

To verify your identity as an authorized entity accessing Maya's endpoints, API Authentication must be performed during transaction requests.

Some of Maya’s API endpoints require Bearer Authentication (also called Token Authentication), which relies on the client token (bearer token) generated by Maya Connect Token API. You must provide this token as part of the Authorization header.

  1. The API Consumer checks if a valid access_token exists.
  2. If the existing access_token has expired or no valid access_token exists, the API Consumer requests a new one from Maya Connect via Create Access Token Endpoint .

This method uses the grant type client_credentials. When referring to the API reference, make sure you are reviewing the CLIENT_CREDENTIALS specifications.

  1. Maya Connect responds with the access_token to the API Consumer.
  2. The API Consumer saves the access_token.
  3. The API Consumer uses the new access_token to invoke Maya's API.

Generating the access_token via Maya Connect

At this point, you should have the following credentials:

  • Valid Client ID
  • Valid Client Secret

These credentials are provided once onboarded. Different credentials will be provided for each environment (e.g. sandbox, production).

Reach out to your Maya Relationship Manager for the onboarding requirements and process.

Providing the correct credentials and following the specifications, send the request with grant type client_credentials to the Create Access Token endpoint to generate an access_token.

Every successful call to this endpoint would generate a time-limited access_token.

access_token Expiry

You may call this endpoint and acquire your client token anytime. Please note that in compliance with the privacy and security regulations of Maya, the access_token has its default lifetime.

access_token3600 seconds

When your access_token expires, send a new request to Maya Connect Token API to generate a new access_token.

Errors for client_credentials grant

invalid_client - Bad client credentials

HTTP Status: 401

Error Message: Bad client credentials.

This is caused by sending a request with the wrong or missing client ID or secret.

Ensure that you have encoded the correct client ID and secret, and it should be in the Authorization header of your HTTP request.

invalid_client - Unauthorized grant type

HTTP Status: 401

Error Message: Unauthorized grant type: refresh_token.

This happens when the grant type is not allowed for the client.

Use only the client_credentials grant type. If you need to use this grant type but have encountered this error, contact your Maya Relationship Manager.

invalid_request - Missing grant type

HTTP Status: 400

Error Message: Missing grant type.

This happens when the grant type is missing in the request.

Ensure to include the grant_type field that is set to client_credentials in the request body.

unsupported_grant_type - Unsupported grant type

HTTP Status: 400

Error Message: Unsupported grant type: <unsupported_type>

This happens when the grant type provided is not supported by Maya Connect.

Ensure to include the grant_type field that is set to client_credentials in the request body.