​
Introduction

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

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.

Caution – API security practices

  • 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.

​
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.

EndpointPOST /v2.01/oauth/token
AuthorizationBasic RXhhbXBsZUNsaWVudElkOlBFQkIwVkRoRkVOZkVoWFRVeW9yVFlqNmhDVm1xTDBIUmJ3WTRnNU4xN3J1aVBqbVFu
Content-Typeapplication/x-www-form-urlencoded
Request bodygrant_type=client_credentials
Response example
{
    "access_token": "094696b3724d4aa5a182eac360dcd537",
    "token_type": "bearer",
    "expires_in": 1199
}
PropertyDescription
access_tokenThe access token to use to authenticate.
token_typeThe 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:

AuthorizationBearer 094696b3724d4aa5a182eac360dcd537

Caution – Use token for its full lifetime

You should 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.

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:

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