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.
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:
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
|
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 |
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 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 |
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:
If your authentication is misconfigured and causes repeated access attempts with invalid credentials, it may result in a temporary blockage on your IP address:
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: