OAuth Token
Contents
We encourage the use of OAuth 2.0 over TLS as an alternative to Mutual TLS for all integrations, having the possibility to have a different token for each provider's resources.
The motivations for this recommendation are:
Example of communication:
Request
POST {url}/oauth/token--header 'Content-Type: application/json'--header 'Authorization: Basic <Base64 encoded $client_id:$client_secret>'--data-raw '{"audience": "<API_IDENTIFIER>","grant_type": "client_credentials"}'
Headers
| Name | Value | Description |
|---|---|---|
| Content-Type | application/json | Expected media type of the resource. |
| Authorization | Basic <Base64 encoded $client_id:$client_secret> | Should be Basic type, the value is the base64 encode of the concatenation of client_id and client_secret using a colon (:) as a separation character. |
The request body will have a JSON object with following fields:
| Name | Type of data | Description | Type |
|---|---|---|---|
| audience | String | Resource name that the token is being requested:
| Mandatory |
| grant_type | String | Valid value:
| Mandatory |
Response
HTTP 200 OK--header 'Content-Type: application/json'{"access_token": "<ACCESS_TOKEN>","token_type": "Bearer","expires_in": 86400}
The response body needs to have following fields:
| Name | Type of data | Description | Type |
|---|---|---|---|
| access_token | String | Access token for the requested resource. | Mandatory |
| token_type | String | Token type, should be alway of type “Bearer” given that client credentials grant type will be used. | Mandatory |
| expires_in | Long | Token expiration time expressed in seconds. | Mandatory |
Status Codes
| Status | Code | Description |
|---|---|---|
| AUTHORIZED | 200 | Authentication with success. |
| BAD REQUEST | 400 | Whenever the request is invalid. |
| UNAUTHORIZED | 401 | In the case that credentials are invalid or it does not have access to requested resource. |
| ERROR | 500 | Any authentication server issue. |
Revocation of OAuth Token
The revocation of OAuth tokens in MercadoLibre resembles the IETF standard, which states that, for the revocation of tokens generated through the OAuth 2.0 protocol, the client can notify the authorization server that a specific access token should no longer be considered valid. Additionally, this feature will allow us to act on demand in response to any eventuality that may arise, regardless of the token's expiration time; in other words, we do not have to wait for the token to expire. The token revocation request is made via an HTTP POST request to the revocation endpoint. This request must include the token that you wish to revoke. The format of the request body must be application/x-www-form-urlencoded and contain a 'token' parameter with the value of the token to be revoked. As a response, the server indicates whether the token was successfully revoked. If successful, the server returns an HTTP status code 200. If the token could not be revoked, an HTTP status code 4xx or 5xx is returned. As a security requirement, the standard establishes measures to ensure that only the legitimate holder of the token can revoke it. This includes the authentication of the client making the revocation request, using a valid access token generated by the audience "revoke," for which the logistics provider must enable token generation.
In addition to authentication, the client must have the appropriate permissions to perform the token revocation (audience). For example, a token can only be revoked by the same client and with the audience "revoke." It should never be possible to revoke a token if the token in the header is the same as the one being requested for revocation.
| Endpoint | Headers | Body | Response |
|---|---|---|---|
| POST https://service_url/oauth/revoke |
|
|
Request
curl -X POST https://service_url/oauth/revoke
-H 'Authorization: Bearer NEW_ACCESS_TOKEN_WITH_REVOKE_AUDIENCE'
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'token=ACCESS_TOKEN_TO_REVOKE'
Response Formats for OAuth Token Revocation
2xx OK
{
"status": "OK"
}4XX FAILED
{
"status": "FAILED",
"message": "Descriptive message indicating the reason for the failure."
}5XX ERROR
{
"status": "ERROR",
"message": "Descriptive message indicating the reason for the server error."
}Testing Suite
There's a section on our test suite (docker) to simulte our API call to /oauth/token with a form to complete required details such as client_id, client_secret and a dropdown to select audience (api identifiers). This docker builds the Authorization Basic header using the credentials provided in the form (client_id and client_secret) encoded with Base64 to be included in the request. To test each integration including the oauth token (Auth, Cancel, Agency Auth, Agency, Booking, Tracking Pull) there's a field in each screen to complete with the token generated manually so that the docker adds the Bearer header with such token on the integration request.