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#

Name	Value	Description
Content-Type	application/json	Expected media type of the resource.
Authorization	Basic <Base64 encoded $client_id:$client_secret>	It should be Basic type. The value is the base64 encoding of the concatenation of client_id and client_secret using a colon (:) as the separator character

Body Parameters#

Name	Data type	Description	Field presence in every request
audience	String	Requested token resource. Allowed values: authorizations tracking-pull agencies booking logistic-feed handling-unit rtt fiscal-info revoke coverage	Always present in the request
grant_type	String	Valid value: client_credentials	Always present in the request

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 }

Name	Data type	Description	Mandatory
access_token	String	Access token for the requested resource.	Mandatory
token_type	String	Token type. It should always be "Bearer" as client credentials grant type will be used.	Mandatory
expires_in	Long	Token expiration time in seconds.	Mandatory

HTTP Status Codes & Errors#

HTTP	Status	Description
200	AUTHORIZED	Authentication with success.
400	BAD REQUEST	Whenever the request is invalid.
401	UNAUTHORIZED	In the case that credentials are invalid or it does not have access to requested resources.
500	ERROR	Any authentication server issue.

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#

Name	Value	Description
Authorization	Bearer NEW_ACCESS_TOKEN_WITH_REVOKE_AUDIENCE	Valid access token generated by the audience "revoke"
Content-Type	application/x-www-form-urlencoded	Request Body Format

Body parameters#

Name	Data type	Description	Field presence in every request
token	String	Token to be revoked	Always present in the request

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 }