Autenticación y Autorización

Para comenzar a utilizar nuestros recursos es necesario que puedas desarrollar los procesos de Autenticación y Autorización. De esta manera, podrás trabajar con los recursos privados del usuario cuando autorice tu aplicación.

Contenidos

→Autenticación
→Autorización
    ↳¿Cómo logramos la autorización?
→Server side
    ↳Paso a paso
    ↳Parámetros
→Refresh token
    ↳Parámetros
→Flujo Server side
→Client side
    ↳Paso a paso
    ↳Parámetros
→Flujo Client side
→Obtén tu access token
→Referencia de códigos de error


Autenticación

El proceso de autenticación es utilizado para verificar la identidad de una persona en función de uno o varios factores, asegurando que los datos de quien los envió sean los correctos. Si bien existen diferentes métodos, en Mercado Libre utilizamos el basado en contraseñas. Los pasos a seguir son:

  1. Autenticate con tu usuario de Mercado Libre.

    2. Notas:
    - En caso de querer usar un usuario de test, ingresa aquí.
    - Recuerda que el usuario que inicie sesión debe ser administrador, para que el ACCESS_TOKEN obtenido tenga los permisos suficientes para realizar las consultas.
    - En caso que el usuario sea operador/colaborador, el grant no será válido.
    - Los siguientes eventos pueden invalidar un ACCESS_TOKEN antes del tiempo de expiración:
    • Cambio de contraseña por parte del usuario.
    • Actualización del App Secret por parte de una aplicación.
    • Revocación de permisos a tu aplicación por parte del usuario.

  2. Coloca la siguiente URL en la ventana de tu navegador para obtener la autorización:

    3. http://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID&redirect_uri=$YOUR_URL
    Nota:
    El atributo YOUR_URL se completa con el valor que se agregó cuando se creó la aplicación.



    - APP_ID: Una vez creada la aplicación, será identificada mediante un ID.

  3. Como último paso, el usuario será redirigido a la siguiente pantalla donde se le solicitará que vincule la aplicación con su cuenta.


    4. Si revisamos la URL, se puede observar que se agregó el parámetro CODE.

    Este CODE, será utilizado cuando se necesite generar un ACCESS_TOKEN, que permitirá el acceso a nuestras API.


Autorización

La autorización es el proceso por el cual permitimos acceder a recursos privados. En este proceso, se deberá definir qué recursos y operaciones se pueden realizar (“sólo lectura” o “lectura y escritura”).


¿Cómo logramos la autorización?

A través del Protocolo OAuth 2.0, uno de los más utilizados en plataforma abiertas (Twitter, Facebook, etc.) y método seguro para trabajar con recursos privados.
Este protocolo nos brinda:

  • Confidencialidad, el usuario no deberá revelar su clave en ningún momento.
  • Integridad, solo podrán ver datos privados aquellas aplicaciones que tengan el permiso de hacerlo.
  • Disponibilidad, los datos siempre estarán disponibles en el momento que se necesiten.

Dentro de este protocolo existen 4 modos de funcionamiento posibles denominados 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

A continuación te mostraremos cómo trabajar con los recursos de Mercado Libre utilizando Server Side o Client Side.


Server side

El flujo Server side es el más adecuado para las aplicaciones que ejecutan código del lado del servidor. Por ejemplo, aplicaciones desarrolladas en lenguajes como Java, Grails, Go, etc. Nosotros te recomendamos que utilices nuestros SDKs ya que te facilitarán la complejidad del flujo de autorización utilizando el protocolo OAuth.


Paso a paso

Importante:
Necesitarás el app_id que obtuviste al crear tu aplicación. Si aún no lo hiciste esta guía te proporcionará los pasos necesarios para hacerlo.
  • Al iniciar el flujo de autorización, la aplicación que desarrolles deberá redireccionar a Mercado Libre para que los usuarios puedan autenticarse y posteriormente autorizar tu aplicación:
    • curl -X POST https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID
    Nota:
    En el ejemplo utilizamos el URL para Argentina (MLA) pero si trabajas en otros países, ten en cuenta cambiar el .com.ar por el dominio del país correspondiente. Mira los países en donde operamos.

    Parámetros

    Response_type: enviando el valor “code” se obtendrá un ACCESS_TOKEN que le permitirá a la aplicación interactuar con Mercado Libre.
    Client_id: es el APP ID de la aplicación que se creó.

  • Una vez que el usuario inicie sesión será redireccionado a la página de autorización de la aplicación. Allí se le presentarán todos los permisos solicitados.

    • Otorgados los permisos el usuario será redireccionado al REDIRECT URI configurado en la aplicación con el ACCESS_TOKEN correspondiente:

    http://YOUR_REDIRECT_URI?code=SERVER_GENERATED_AUTHORIZATION_CODE
  • El código de autorización es utilizado para intercambiarlo por un ACCESS_TOKEN:

    • Debes realizar un POST sin BODY:

    curl -X POST https://api.mercadolibre.com/oauth/token?grant_type=authorization_code&client_id=$APP_ID&client_secret=$SECRET_KEY&code=$SERVER_GENERATED_AUTHORIZATION_CODE&redirect_uri=$REDIRECT_URI

    Respuesta:

    {
    "access_token": "APP_USR-5387223166827464-090515-8cc4448aac10d5105474e135355a8321-8035443",
    "token_type": "bearer",
    "expires_in": 10800,
    "scope": "offline_access read write",
    "user_id":8035443,
    "refresh_token": "TG-5b9032b4e4b0714aed1f959f-8035443"
}

    Parámetros

    grant_type: authorization_code – Indica que la operación deseada es intercambiar el “code” por un ACCESS_TOKEN.
    client_id: es el APP ID de la aplicación que se creó.
    client_secret: es Secret Key que se generó al crear la aplicación.
    code: el código de autorización obtenido en el paso anterior.
    redirect_uri: el redirect URI configurado para tu aplicación o uno de los dominios permitidos.
    ¡Listo! Ya puedes utilizar el ACCESS_TOKEN para realizar llamadas a nuestra API y así obtener acceso a los recursos privados del usuario.


    Refresh token

    Ten en cuenta que el ACCESS_TOKEN generado expirará transcurridas 6 horas desde que se solicitó. Por eso, para asegurar que puedas trabajar por un tiempo prolongado y no sea necesario solicitar constantemente al usuario que se vuelva a loguear para generar un token nuevo, te brindamos la solución de trabajar con un refresh token.

    Importante:
    Para eso, la aplicación debe tener seleccionada la opción offline_access.

    Cada vez que realices la llamada que intercambie el code por un ACCESS_TOKEN, también vendrá el dato de un refresh_token, que deberás guardar para intercambiarlo por un nuevo ACCESS_TOKEN una vez que expire.
    Para renovar tu ACCESS_TOKEN debes efectuar la siguiente llamada:

    curl -X POST https://api.mercadolibre.com/oauth/token?grant_type=refresh_token&client_id=$APP_ID&client_secret=$SECRET_KEY&refresh_token=$REFRESH_TOKEN

    Parámetros

    grant_type: refresh_token indica que la operación deseada es actualizar un token.
    refresh_token: el refresh token del paso de aprobación guardado previamente.
    client_id: es el APP ID de la aplicación que se creó.
    client_secret: es Secret Key que se generó al crear la aplicación.

    Respuesta:

    {
    "access_token": "APP_USR-5387223166827464-090515-b0ad156bce700509ef81b273466faa15-8035443",
    "token_type": "bearer",
    "expires_in": 10800,
    "scope": "offline_access read write",
    "user_id":8035443,
    "refresh_token": "TG-5b9032b4e4b0714aed1f959f-8035443"
}

    La respuesta incluye un nuevo ACCESS_TOKEN válido por 6 horas más y un nuevo REFRESH_TOKEN que necesitarás guardar para utilizarlo cada vez que expire.

    Importante:
    - Solo permitimos utilizar el último REFRESH_TOKEN generado para hacer el intercambio.
    - Para optimizar los procesos de tu desarrollo, te sugerimos que renueves tu ACCESS_TOKEN únicamente cuando pierda validez.

    Flujo Server side

    En resumen, el proceso que estarás realizando es el siguiente:

    flujo_serverside

    Referencias

    1. Redirecciona la aplicación a Mercado Libre.
    2. No tienes que preocuparte por la autenticación de los usuarios a Mercado Libre, ¡nuestra plataforma se encargará de ello!
    3. Página de autorización.
    4. POST para intercambiar el código de autorización por un ACCESS_TOKEN.
    5. La API de Mercado Libre intercambia el código de autorización por un access token.
    6. Ya puedes utilizar el ACCESS_TOKEN para realizar llamadas a nuestra API y así obtener acceso a los datos privados del usuario.

    a- Redirect

    curl -X  POST https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID&redirect_uri=$REDIRECT_URL

    b- GET

    curl -X GET http://YOUR_REDIRECT_URI?code=$SERVER_GENERATED_AUTHORIZATION_CODE

    c- POST

    curl -X POST https://api.mercadolibre.com/oauth/token?grant_type=authorization_code&client_id=$APP_ID&client_secret=$SECRET_KEY&code=$SERVER_GENERATED_AUTHORIZATION_CODE&redirect_uri=$REDIRECT_URI

    Client side

    Este flujo es el más adecuado para las aplicaciones que ejecutan código del lado del cliente. Por ejemplo las desarrolladas en lenguaje Javascript/Ajax, Angular, Mobile, entre otros. Te recomendamos que utilices nuestros SDKs ya que te facilitarán la complejidad del flujo de autorización utilizando el protocolo OAuth.

    Importante:
    Al utilizar este flujo no podrás obtener un refresh token. Una vez que el token expire, deberás redireccionar al usuario nuevamente al URL de autorización para obtener el nuevo access token.

    Paso a paso

    Importante:
    Necesitarás el APP_ID que obtuviste al crear tu aplicación. Si aún no lo hiciste, esta guía te proporcionará los pasos necesarios para hacerlo.
    1. Al iniciar el flujo de autorización, la aplicación que desarrolles deberá redireccionar a Mercado Libre para que los usuarios puedan autenticarse y posteriormente autorizar tu aplicación:
      2. curl -X POST https://auth.mercadolibre.com.ar/authorization?response_type=token&client_id=$APP_ID
      Nota:
      En el ejemplo utilizamos el URL para Argentina (MLA) pero si estás trabajando en otros países ten en cuenta cambiar el .com.ar por el dominio del país correspondiente. Mira los países donde opera Mercado Libre.

      Parámetros

      Response_type: enviando el valor “token” se obtendrá un access token que le permitirá a la aplicación interactuar con Mercado Libre.
      Client_id: es el APP ID de la aplicación que se creó.


    2. Una vez que el usuario inicie sesión será redireccionado a la página de autorización de la aplicación donde se presentarán todos los permisos solicitados.

      3. Cuando los permisos sean otorgados, el usuario será redireccionado al REDIRECT URI configurado en la aplicación con el access token correspondiente:

      http://YOUR_URL?access_token=$ACCESS_TOKEN&expires_in=10800&user_id=$USER_ID&domains=$APP_DOMAINS

      Parámetros

      Access_token: llave de acceso a los recursos privados.
      Expires_in: vida útil del access token en segundos.
      Domains: dominio de la redirect URI.

      ¡Listo! Ya puedes utilizar el ACCESS_TOKEN para realizar llamadas a nuestra API y así obtener acceso a los recursos privados del usuario.


      Por ejemplo, para acceder a la información privada del usuario:

      curl -X GET https://api.mercadolibre.com/users/me?access_token=$ACCESS_TOKEN

      Flujo Client side

      En resumen, el proceso que estarás realizando es el siguiente:

      Flujo_ClientSide

      Referencias

      1. Redirecciona la APP a Mercado Libre.
      2. No tienes que preocuparte por la autenticación de los usuarios a Mercado Libre, ¡nuestra plataforma se encargará de ello!
      3. Página de autorización.
      4. Ya puedes utilizar el ACCESS_TOKEN para realizar llamadas a nuestra API y así obtener acceso a los datos privados del usuario.

      a- POST

      curl -X POST https://auth.mercadolibre.com.ar/authorization?response_type=token&client_id=$APP_ID

      Ten en cuenta cambiar el .com.ar por el dominio del país correspondiente.

      b- GET

      curl -X GET http://YOUR_URL?access_token=$ACCESS_TOKEN&expires_in=10800&user_id=$USER_ID&domains=$APP_DOMAINS

      Obtén tu access token

      Introduzca el ID de la aplicación creada: *Por favor, ingrese un ID válido de la aplicación

        
    -

      Referencia de códigos de error

      invalid_client: el client_id y/o client_secret de tu aplicación provisto es inválido.
      invalid_grant: la autorización provista es inválida, expiró, fue revocada; el client_id o el redirect uri no coinciden con el original.
      invalid_scope: el alcance solicitado es inválido, desconocido o está mal formado. Los valores permitidos para el parámetro alcance son: “offline_access”,”write”,”read”.
      invalid_request: la solicitud no incluye un parámetro obligatorio, incluye un parámetro o valor de parámetro no soportado, hay algún valor duplicado o está mal formada de otro modo.
      unsupported_grant_type: los valores permitidos para grant_type son “authorization_code” o “refresh_token”.
      forbidden: la llamada no autoriza el acceso, posiblemente se está utilizando el token de otro usuario.


      Siguiente: Consulta usuarios.