Access control - OAuth

Direction: This page covers how carriers authenticate to call Mercado Envios APIs (carrier → MELI). For the reverse flow — how Mercado Envios authenticates to call carrier endpoints — see Carrier OAuth Token.

Create your account and your application

In order to communicate with our API, the carrier should be

  1. Create a business account at https://www.mercadolibre.com/

  2. Once the account is created, you should follow next steps in order to create the application:

    Once logged in, go to https://applications.mercadolibre.com/ and select origin country.

    Link developer's site account to user's account. Click on "Vincular" (Link Account).

    Now proceed to create the new application.

    Once you are logged in, you should go to "Mis Aplicaciones" (My Applications) section.

    Click on "Crear nueva aplicación" (Create new application).

    Note: If you already have an application, then edit it to complete the next steps:

    Complete the fields and click on "Continuar" (Continue):

    In the next part, you will have to complete the "Redirect URI" and "Notificaciones callbacks URL" with any https url.

    Finally, press the button "Crear" (Create).

    This will provide you an APP ID. Once created, you can check it out on "Mis aplicaciones" (My Applications) section.

    Also, the created application can be checked at the following endpoint using the client_id (applicationId) as a parameter.

    https://api.mercadolibre.com/applications/{YOUR_CLIENT_ID}

  3. Once the app ID and secret key are generated, you will be able to get the access_token in order to communicate with our API.

Note: The app ID must be informed to Mercado Libre in order to grant the required access.

How to get my Access Token

In order to guarantee that only authorized users send notifications, an authorized application token is required.

How to get my access token?

Request:

bash
1POST api.mercadolibre.com/oauth/token
json
1{
2    "client_id": "{YOUR_CLIENT_ID}",
3    "client_secret": "********ASSDF",
4    "grant_type": "client_credentials"
5}

Parameters:

  • grant_type: client_credentials used when applications request an access token, using only their credentials, to access to their own resources, not on behalf of a user.
  • client_id: is the APP ID of the application that was created.
  • client_secret: is the Secret Key that was generated when creating the application.

Response:

json
1{
2    "access_token": "APP_USR-{YOUR_CLIENT_ID}-{TIMESTAMP}-{TOKEN}-{USER_ID}",
3    "token_type": "bearer",
4    "expires_in": 21600,
5    "scope": "offline_access read write",
6    "user_id": 281033969
7}

Response Error:

json
1{
2    "message": "invalid client_id or client_secret",
3    "error": "invalid_client",
4    "status": 400,
5    "cause": []
6}

Error Code Reference

  • invalid_client: the client_id and/or client_secret of your application provided is invalid.
  • invalid_grant: this error can occur for various reasons related to the authorization_code and refresh_token. It could be because the authorization_code or refresh_token are invalid, were revoked or expired, were sent in the wrong flow, belong to another client, or if the redirect_uri used in the authorization flow does not match the one configured in your application.
  • invalid_scope: the requested scope is invalid, unknown, or malformed. The allowed values for the scope parameter are: "offline_access", "write", "read".
  • invalid_request: the request does not include a required parameter, includes an unsupported parameter or parameter value, is a duplicate value, or is otherwise malformed.
  • unsupported_grant_type: allowed values for grant_type are "client_credentials", "authorization_code" or "refresh_token".
  • forbidden (403): the call does not authorize access, possibly because you are using another user's token, or in the case of a grant, the user does not have access to the Mercado Libre URL of their site (.ar, .br, .mx, etc.) and should verify that their connection or browser is working correctly for the MELI domain.
  • local_rate_limited (429): due to excessive calls, the request is temporarily rejected. Try again in a few seconds.
  • unauthorized_client: the application does not have authorization for the requested user or the existing authorization does not authorize the scopes with which you want to create the token.
  • unauthorized_application: the application is blocked, therefore, it is not possible to operate until the issue is resolved.

What happens with my access_token after 6 hours?

A new token must be requested through "client_credentials" (previous POST). This action avoids the expiration of the previous access token by the creation of a new one.

Important: There must be as many access tokens as nodes that make requests simultaneously (do not generate an access token for every request). Each token must be regenerated before the expiration date (6 hours).