Authentication

Introduction

The Mangopay REST API uses the OAuth 2.0 authentication protocol to provide secure access to resources. 

Caution – API security practices

• Overuse of the OAuth token endpoint is a security risk and may result in rate limiting or blocking actions from Mangopay. You must ensure you use your authentication token for the full duration of its lifetime for all subsequent calls (and not renew it every call, see Step 2 below).
• HTTPS is mandatory for production environments
• You must call the API from your server. Calling the API from the browser is a security risk and is not supported by Mangopay.

Note – SDKs handle authentication automatically

For SDKs, the authentication is handled automatically after the initialization, relying on the OAuth 2.0 protocol. See the SDK authentication section for more details.

The SDKs also handle mTLS authentication, which your platform additionally needs to integrate if you are using proxy management to take SCA-triggering actions on behalf of users.

OAuth 2.0 authentication

The OAuth 2.0 method of authentication consists in generating a temporary authentication token, called a Bearer token. This can then be used as tokenized credentials until it expires, at which point a new token must be generated. The logic is as follows:

1. Generate a Bearer token
2. Use the Bearer token for its full lifetime
3. Generate a new one before expiry

Since you only send your API key to generate the token, this industry-standard method ensures a high level of security.

You need a ClientId and an API key – you can create these in the Mangopay Dashboard (or else contact Sales to get started).

1. Generate a Bearer token

To generate your authentication token, call the endpoint below using Basic Access authentication as follows:

A. Combine your ClientId and API key into a string separated by a colon

ClientId:ApiKey

B. Encode the string in Base64

Once encoded, the string looks something like this:

RXhhbXBsZUNsaWVudElkOlBFQkIwVkRoRkVOZkVoWFRVeW9yVFlqNmhDVm1xTDBIUmJ3WTRnNU4xN3J1aVBqbVFu

C. Call the OAuth token endpoint

Use the encoded string, preceded by “Basic” and a space, as your Authorization header. Unlike most other calls to the API, this endpoint supports Basic Access authentication and accepts the x-www-form-urlencoded Content-Type.

Endpoint	POST /v2.01/oauth/token
Authorization	Basic RXhhbXBsZUNsaWVudElkOlBFQkIwVkRoRkVOZkVoWFRVeW9yVFlqNmhDVm1xTDBIUmJ3WTRnNU4xN3J1aVBqbVFu
Content-Type	application/x-www-form-urlencoded
Request body	grant_type=client_credentials

Response example

{
    "access_token": "094696b3724d4aa5a182eac360dcd537",
    "token_type": "bearer",
    "expires_in": 1199
}

Property	Description
access_token	The access token to use to authenticate.
token_type	The type of token: Bearer.
expires_in	The number of seconds until the access_token expires and a new token needs to be generated. Default values: 3600 (in Production), 1200 (in Sandbox) Note: The value may differ from the default values, therefore you should not rely on hard-coded defaults but on the expires_in value returned.

2. Use the Bearer token for its full lifetime

Now that you have your Bearer access_token, you can use it to authenticate all other API calls for the expires_in duration.

To do so, add it to the Authorization header of your requests, preceded by “Bearer” and a space:

Authorization	Bearer 094696b3724d4aa5a182eac360dcd537

Overuse of OAuth token endpoint

Caution – Use token for its full lifetime

Overuse of the OAuth token endpoint is a security and performance risk and may result in rate limiting or blocking actions from Mangopay.

You must use the token on all other API calls until a new token is needed. Requesting a new token too often results in unnecessary API calls and can put avoidable strain on your server and Mangopay’s.

Base your integration dynamically on the expires_in and do not hard-code the default value. We recommend triggering a new OAuth token call 30 seconds before the expires_in value.

3. Generate a new token before expiry

Shortly before your token expires (we recommend 30 seconds), generate a new one with the OAuth token endpoint as described in Step 1C above.

HTTP errors

Once the token expires (that is, the expires_in seconds value elapses), then it is no longer valid and calls made with it will return the following HTTP 401 error: 

401 - Authorization credentials not valid

{
    "Message": "The authorization credentials are not valid",
    "Type": "invalid_credentials",
    "Date": 1733404277
}

If your authentication is misconfigured and causes repeated access attempts with invalid credentials, it may result in a temporary blockage on your IP address:

400 - Account temporarily blocked

{
    "error": "unauthorized_client",
    "error_description": "This account has been temporarily locked for security reasons. Please try again later."
}

SDK authentication

With our official SDKs, you don’t have to worry about the logic behind the authentication to Mangopay: you just need to set your credentials after the SDK initialization.

The authentication is then handled automatically, relying on OAuth 2.0 to provide a secure connection to Mangopay.

Please find below examples of how to set your credentials after the SDK initialization to authenticate:

PHP

$api = new MangoPay\MangoPayApi();
$api->Config->ClientId = 'your-client-id';
$api->Config->ClientPassword = 'your-client-api-key;