Carrier OAuth Token#

Overview#

The client authentication process for each integration is based on the OAuth 2.0 mechanism, requiring both token generation and token revocation to be mandatory for a completed integration. A unique token is generated for every carrier resource. The integration must be capable of generating multiple tokens, one for each specific audience. The token duration is 6 hours.

Key Features

• The endpoint needs to be secured using a client_id and client_secret, both need to be provided by the provider in a very secure way.
• The client_id and client_secret will be sent as the basic Authentication header.
• The client_id and client_secret never will be sent as part of the body request.
• The request body will have the necessary information to identify the integration flow such as fields audience and grant_type (where grant_type must be set to client_credentials).

Example of communication:

HTTP Request#

bashCopy
1POST {url}/oauth/token
2 --header 'Content-Type: application/json'
3 --header 'Authorization: Basic <Base64 encoded $client_id:$client_secret>'
4 --data-raw '{
5  "audience": "<API_IDENTIFIER>",
6  "grant_type": "client_credentials"
7 }'

Request Parameters#

Headers parameters#

Body Parameters#

Response#

Successful Response (HTTP 200)#

bashCopy
1HTTP 200 OK
2 --header 'Content-Type: application/json'
3 {
4  "access_token": "<ACCESS_TOKEN>",
5  "token_type": "Bearer",
6  "expires_in": 21600
7 }

HTTP Status Codes & Errors#

OAuth Token Revocation#

Overview#

OAuth token revocation at MercadoLibre follows the IETF standard, allowing the client to notify the authorization server that a specific access token, generated using the OAuth 2.0 protocol, must be immediately invalidated. This functionality is crucial as it allows acting on demand in the event of any contingency, without having to wait for the token to expire.

Crucial Restriction:

The token used in the header to authenticate the revocation request must never be the same token that is requested to be revoked.

HTTP Request#

bashCopy
1curl -X POST https://service_url/oauth/revoke
2  --header 'Authorization: Bearer NEW_ACCESS_TOKEN_WITH_REVOKE_AUDIENCE'
3  --header 'Content-Type: application/x-www-form-urlencoded'
4  --data-raw 'token=ACCESS_TOKEN_TO_REVOKE'

Request Parameters#

Header parameters#

Body parameters#

Response#

Successful Response (HTTP 200)#

bashCopy
1HTTP 200 OK
2 --header 'Content-Type: application/json'
3 {
4  "status": "OK"
5 }

Failed Response (HTTP 400)#

bashCopy
1HTTP 400 Bad Request
2 --header 'Content-Type: application/json'
3 {
4  "status": "FAILED",
5  "message": "Descriptive message indicating the reason for the failure"
6 }

Failed Response (HTTP 500)#

bashCopy
1HTTP 500 Internal Server Error
2 --header 'Content-Type: application/json'
3 {
4  "status": "ERROR",
5  "message": "Descriptive message indicating the reason for the failure"
6 }