Authentication and Authorization

Mercado Libre platform allows you to work with our API public and private resources, via HTTP calls using GET, PUT, POST, DELETE and OPTIONS.
Public resources, such as available sites and categories, can be anonymously accessed, while private resources and user-own actions, such as listing an item, giving feedback or viewing purchase/sale information, require application-based authorization.
This guide explains the meaning of authentication and the authorization flow to be followed to obtain an access_token (access key to private resources for each user granting authorization to the application – valid for 6 hours).
For example:
Without access_token (Public Resource)

https://api.mercadolibre.com/users/226384143/

{
  "id": 226384143,
  "nickname": "TETE9928972",
  "registration_date": "2016-08-25T11:36:00.000-04:00",
  "country_id": "AR",
  "address": {
    "state": "AR-C",
    "city": "Palermo"
  },
  "user_type": "normal",
  "tags": [
    "normal",
    "test_user",
    "user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE9928972",
  "seller_reputation": {
    "level_id": null,
    "power_seller_status": null,
    "transactions": {
      "period": "historic",
      "total": 1,
      "completed": 1,
      "canceled": 0,
      "ratings": {
        "positive": 0,
        "negative": 0,
        "neutral": 1
      }
    }
  },
  "buyer_reputation": {
    "tags": [
    ]
  },
  "status": {
    "site_status": "active"
  }
}


With access_token (Private Resource)

 
 https://api.mercadolibre.com/users/226384143?access_token=$ACCESS_TOKEN

{
  "id": 226384143,
  "nickname": "TETE9928972",
  "registration_date": "2016-08-25T11:36:00.000-04:00",
  "first_name": "Test",
  "last_name": "Test",
  "country_id": "AR",
  "email": "test_user_38730994@testuser.com",
  "identification": {
    "type": "DNI",
    "number": "1111111"
  },
  "address": {
    "state": "AR-C",
    "city": "Palermo",
    "address": "Test Address 123",
    "zip_code": "1414"
  },
  "phone": {
    "area_code": "01",
    "number": "1111-1111",
    "extension": "",
    "verified": false
  },
  "alternative_phone": {
    "area_code": "",
    "number": "",
    "extension": ""
  },
  "user_type": "normal",
  "tags": [
    "normal",
    "test_user",
    "user_info_verified"
  ],
  "logo": null,
  "points": 100,
  "site_id": "MLA",
  "permalink": "http://perfil.mercadolibre.com.ar/TETE9928972",
  "shipping_modes": [
    "custom",
    "not_specified"
  ],
  "seller_experience": "ADVANCED",
  "bill_data": {
    "accept_credit_note": null
  },
  "seller_reputation": {
    "level_id": null,
    "power_seller_status": null,
    "transactions": {
      "period": "historic",
      "total": 1,
      "completed": 1,
      "canceled": 0,
      "ratings": {
        "positive": 0,
        "negative": 0,
        "neutral": 1
      }
    }
  },
  "buyer_reputation": {
    "canceled_transactions": 0,
    "transactions": {
      "period": "historic",
      "total": null,
      "completed": null,
      "canceled": {
        "total": null,
        "paid": null
      },
      "unrated": {
        "total": null,
        "paid": null
      },
      "not_yet_rated": {
        "total": null,
        "paid": null,
        "units": null
      }
    },
    "tags": [
    ]
  },
  "status": {
    "site_status": "active",
    "list": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "buy": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "sell": {
      "allow": true,
      "codes": [
      ],
      "immediate_payment": {
        "required": false,
        "reasons": [
        ]
      }
    },
    "billing": {
      "allow": true,
      "codes": [
      ]
    },
    "mercadopago_tc_accepted": true,
    "mercadopago_account_type": "personal",
    "mercadoenvios": "not_accepted",
    "immediate_payment": false,
    "confirmed_email": false,
    "user_type": "simple_registration",
    "required_action": ""
  },
  "credit": {
    "consumed": 101.1,
    "credit_level_id": "MLA1"
  }
}

Contents:

Authentication

Authentication is the act or process of determining or confirming whether someone or something is, in fact, who or what it is declared to be.
In the case of a person, authentication consists in verifying his/her identity based on one or several factors, ensuring the sender’s data are correct.

Some authentication methods are:

  • Biomedical methods, fingerprints or retinal scan, etc.
  • Smart cards that save a user´s certificate information.
  • Standard methods based on passwords.
  • For example, to log into Mercado Libre we authenticate ourselves by entering our user name and password.

login

Authorization

Authorization is the process whereby we allow someone or something to access private resources.
The authorization should define which resources and operations can be performed, since it is not the same to grant read-only than read and write access.

How do we obtain authorization? Via the OAuth 2.0 Protocol, which is one of the most widely used protocols in open platforms (Twitter, Facebook, etc.) and a secure method to work with private resources.

OAuth offers:

  • Confidentiality, the user will never have to disclose his/her key.
  • Integrity, private data can only be viewed by applications with permits to do so.
  • Availability, data will always be available, on a need basis.

This protocol offers 4 possible operating modes, called Grant Types:

– The Authorization Code Grant Type (Server Side)
– The Implicit Grant Type (Client Side)
– The Password Credentials Grant Type
– The Client Credentials Grant Type

Although each of them is used for different purposes depending on the service being developed, below you will find the explanation of the first two types since they will allow you to work with our resources and develop tools for every user in Mercado Libre.

Client-side

The Client-side authorization flow is better suited for applications executing the client-side code, e.g., applications developed in javascript/ajax, Angular or mobile applications.
For more information about this flow, go to the tutorial “Client-Side Authorization

Server-side

The Server Side authorization flow is better suited for applications executing the server-side code, such as, applications developed in Java, Grails, Go, etc.
Note: This option will be helpful for applications executing cron jobs, to update product stock or operate when the user is not directly interacting with the application.
For more information about this flow, go to the tutorial “Server-Side Authorization

Get your access_token!

Enter the application ID you have just created:

*Please enter a valid Application ID
User informationJSON Response

-

Use our SDKs

Using our SDKs the authentication process will be simpler since our SDKs save you from coding the whole OAuth protocol from scratch.
Our community is already using them!
We already provide SDKs for:

If you find an enhancement or have a suggestion, you can share it with the community creating a Pull Request within our GitHub repository.

Considerations

Token validity and expiration
When you get an access_token, it will be immediately valid and usable to make requests to the API for a limited period of 6 hours.
There are also events which may cause an access_token to become invalid before the expiration time. For example: user changing his/her password, an application refreshing its App Secret and, of course, a user revoking permissions to your application.

Error Codes Reference

ErrorDescriptionPossible 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_scopeThe 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”.
forbidden

The caller is not authorized to access this resource

The caller is not authorized to access.It is using the token of another user.



Next topic: Manage user


Related articles:

Server side authentication flow

Client side authentication flow

Please rate this