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

  • Generate a Bearer token
  • Use the Bearer token until it expires
  • 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 RXhhbXBsZU…J1aVBqbVFu
Content-Typeapplication/x-www-form-urlencoded
Request bodygrant_type=client_credentials
API response
{
    "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 will need 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 your Bearer token until it expires

Now that you have your Bearer access_token, you can use it to access Mangopay API resources until it expires.

Use the token, preceded by “Bearer” and a space, as the Authorization header in your requests:

AuthorizationBearer 094696b3724d4aa5a182eac360dcd537

​
3. Generate a new token before expiry

Before your token expires, generate a new one with the OAuth token endpoint as described above. 

Best practice – Only generate new tokens when the last one expires

There is no need to generate a different token for every call you make – only before the previous one expires.

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",
    "Id": "9e1f5654-2957-408b-a198-e921ca6830b7",
    "Date": 1700772361.0,
    "errors": null
}

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:

Was this page helpful?

IntroductionRate limiting