Overview

The MercadoLibre platform lets you access different resources through API calls. As you already know, there are some public resources that can be accessed anonymously (such as product search) and other resources that require some kind of authentication (user data, payments, modify your listed products).

To handle the authentication within the platform we use OAuth 2.0 protocol. This is a standard, secure yet simple protocol that covers most usage cases you should encounter when interacting with MercadoLibre’s APIs.

We will explain shortly how to use OAuth 2.0 authentication in some simple cases and you can read further in the following sections.

Table of Contents

Should I read all this?

We definitely think you should. It is always good to know what is happening behind the scenes when you use a sdk/framework. however, we encourage you to use our provided SDKs to connect and “talk” to the APIs.

Using the SDKs has 2 advantages, it saves you from coding the whole OAuth protocol from scratch and you benefit from using code that has been tested by the community. And on the other hand, every security issue or bug discovered can be fixed on a centralized place. If you think that there should be any enhancements please feel free to contribute to these SDKs. It is a win-win situation.

Note: Note: We covered the server-side flows in PHP, Java and .NET, and client-side flows in javascript. If you plan to develop in other programming languages or for mobile content, you will have to code the OAuth flows by yourself or contribute with an SDK to be used by all of us.

Basic concepts

The basic idea behind OAuth protocol is that you need a token to make a secure call to an API. The rest of this guide will explain why this is needed and how to obtain that token whether you are working with client-side or server-side scripting.

What is a token? Why do I need one?

A token is an encrypted string that represents the user credentials. If you have a valid token our servers can know which application is making the call, on behalf of which user, and with which permissions, making sure that all of this is authorized by the user.

More about authentication and Authorization

At a high level the OAuth 2.0 protocol involves three different steps: User Authentication (login), Application Authorization and Application Authentication.

1. User Authentication: This step verifies the user’s identity by redirecting the user to MercadoLibre’s login URL.

login_auth

2. Application Authorization: After login the user will have the opportunity to grant permission to your application, including any capabilities used and data needed.
In the OAuth protocol this is called “user consent”.

authorization

3. Application Authentication: If the user agrees to grant your app those permissions, your application will be sent an access token or an authorization code (which will be used later to obtain an access token).
If the user does not grant permission, MercadoLibre OAuth API returns an error.

Once your application is issued an access token, it can use it in a request to MercadoLibre APIs to request data that belongs to the user or to perform an action on his or her behalf.

How do I get that token?

There are two main flows to obtain an access token:

Existing SDKs

We already provide SDKs for

All of them implement OAuth flows and you are free to add new functions. Just fork repo on GitHub.

oAuth with our SDK.

MELI.init({client_id: 8705});
MELI.login(function() {
//Your code here
});
$meli = new Meli(123456, "application_secret");

if($_GET['code']):
  $oAuth = $meli->authorize($_GET['code'], 'http://localhost/PHPSDK/examples/example_login.php');
  $_SESSION['access_token'] = $oAuth['body']->access_token;
else:
  echo 'Login with MercadoLibre';
endif;
Meli m = new Meli(1234, "a secret");
String redirectUrl = m.getAuthUrl("http://yourcallbackurl/");
m.authorize("the received code", "http://somecallbackurl");
Meli m = new Meli(1234, "a secret");
string redirectUrl = m.GetAuthUrl("http://yourcallbackurl/");
m.Authorize("the received code", "http://somecallbackurl");
meli = Meli(client_id=1234, client_secret="a secret")
redirectUrl = meli.auth_url(redirect_URI="http://somecallbackurl")
meli.authorize(code="the received code", redirect_URI="http://somecallbackurl")
meli = Meli.new(1234, "a secret", "Access_Token", "Refresh_Token")
redirectUrl = meli.auth_url("http://somecallbackurl")
meli.authorize("the received code", "http://somecallbackurl")

Some notes about tokens

Token validity and expiration

When you obtain an access token, it will be valid immediately and usable in requests to the API for a limited period. After that period has elapsed, the access token is considered to have expired and the user will need to be authenticated again in order for your app to obtain a fresh access token. The duration for which a given access token is valid depends on how it was generated.
There are also events which may cause an access token to become invalid before its expected expiration time. Such events include the user changing his password, an application refreshing its App Secret and, of course, the user revoking permissions to your app. Dealing with varying access token expiration times, and handling the case when an access token becomes invalid before its expected expiration time is essential for building a robust application.
If the user has provided you with offline access, then by using the server-side authentication flow you will have a refresh token. This extra token can be used to refresh an expired token (not a token invalidated from other methods). By issuing a POST call to

you will get a new access_token and also a new refresh token. Note that a refresh token can be used only once.

Error Codes Reference

Error_code Error message Description Possible solution
invalid_client invalid client_id or client_secret Invalid client_id and/or client_secret provided. Check your application info and verify parameters client_id and client_secret
invalid_grant To create an access token the user {0} must have an active session, or your application should request authorization for offline_access scope. The provided authorization grant is invalid, expired, revoked, or does not match the redirection URI used in the authorization request. Verify the parameter redirect_uri is the same configured in your application (App Manager), if this not solve, do a new request to obtain a new code.
invalid_grant Error validating grant. Your authorization code or refresh token may have expired or it has already been used. It has expired or it has already been used. Make a new request to obtain one new code or refresh_token.
invalid_grant The client_id does not match the original. Client ID does not match. The parameter client_id wasn’t found, to get your client_id, consult your application (App Manager).
invalid_grant The redirect_uri does not match the original. Redirect URI does not match the original. The parameter redirect_uri is not the same configured in you application, to get your a redirect_uri, consult your application (App Manager)
invalid_scope Invalid scope. The requested scope is invalid, unknown, or malformed. The values allowed for parameter scope are: “offline_access”,”write”,”read”.
invalid_request Wrong number of parameters with duplicate values. The request is missing a required parameter, includes an unsupported parameter or parameter value, or is otherwise malformed. Verify that the parameters sent are valid and are not duplicated.
unsupported_grant_type Unsupported grant type: ${0}. The authorization grant type is not supported by the authorization server. The values allowed for parameter grant_type are “authorization_code” or “refresh_token”.

Please, rate this article