Authentication and Authorization

To start using our resources you need to develop the processes of Authentication and Authorization. This way, you can work with the private resources for each user once authorization is granted by your application.

Contents

→Authentication
→Authorization
→Server side
    ↳Step by step
    ↳Parameters
→Refresh token
    ↳Parameters
→Error codes reference


Authentication

The process of authentication is used to verify a person’s identity based on one or several factors, ensuring the sender’s data are correct. Although there are different methods, in Global Selling we authenticate ourselves by entering our username and password. These are the steps to follow:

  1. Authenticate yourself with your Mercado Libre username.


  2. Notes:
    - The user that logs in has to be a manager, so that the obtained access_token grants the sufficient permits to make the queries.
    - If the user is operator/partner, the grant will be invalid.
    - The following events may cause an access_token to become invalid before its expiration time:
      • User changing his/her password.
      • An application refreshing its App Secret.
      • A user revoking permissions to your application.

  3. Put the following URL in your browser window to get authorization:
  4. http://global-selling.mercadolibre.com/authorization?response_type=code&client_id=$APP_ID&redirect_uri=$YOUR_URL
    Note:
    The attribute YOUR_URL is completed with the value added when the app was created.



    - APP_ID: Once the application is created, it will be identified by an ID.

    Example:

    If when the app was created it was done with Redirect URI:




    It is necessary that the request to the resource /authorization be as follows:

    http://global-selling.mercadolibre.com/authorization?response_type=code&client_id=$APP_ID&redirect_uri=https://global-selling.com/
    Important:
    The redirect_uri has to match exactly what was entered when the application was created to avoid getting the following error:



  5. As a final step, the users will be redirected to the following screen where they will be requested to associate the application with their account.


  6. If we check the URL, it can be observed that the parameter CODE was added.

    http://YOUR_REDIRECT_URI?code=$SERVER_GENERATED_AUTHORIZATION_CODE

    This Code will be used when an access token needs to be generated, it will grant access to our API.


Authorization

Authorization is the process whereby we allow someone or something to access private resources. In this process, it must be defined which resources and operations can be performed (“read only” or “read and write”).


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.
This protocol offers:

  • Confidentiality, users will never have to disclose their keys.
  • Integrity, private data can only be viewed by applications with permits to do so.
  • Availability, data will always be available on a need basis.

Within this protocol there are 4 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

Below, we will show you how to work with Mercado Libre resources using Authorization Code Grant Type.


Server side

The Server side flow is better suited for applications executing the server-side code. Such as, applications developed in PHP, Python, Java y Go. We recommend you to use our SDKs since they will simplify the complexity of the authorization flow by using the protocol OAuth.
To sum up, the process you will be doing is the following:

flujo_serverside_eng

References

  1. Redirects the app to Global Selling.
  2. You do not have to worry about the authentication of the users of Global Selling, our platform will take care of it!
  3. Authorization site.
  4. POST to exchange the authorization code for an access token.
  5. The Global Selling API exchanges the authorization code for an access token.
  6. You can now use the access token to make requests to our API and obtain access to the private resources of the user.

Step by step

Important:
You will need the app_id that you obtained when you created the application. If you haven’t done it yet, this guide will give you the necessary steps to do so.
  1. When initiating the authorization flow, the application you develop must redirect to Global Selling so the users can authenticate themselves and, then, authorize your application.
    In the browser enter the following address:
  2. https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID
    Note:
    In the example we use the URL for Mexico (MLM) but if you are working in other countries remember to change the .com.ar for the domain of the corresponding country. See the list of countries we operate in.

    Parameters

    Response_type: sending the value code you will obtain an access token that will allow you to interact with Mercado Libre.
    Client_id: Is the APP ID of the application that you created.

    For added security, we recommend that you include the state parameter in the authorization URL to ensure that the response belongs to a request initiated by your application.
    In case you do not have a secure random identifier, you can create it using SecureRandom and it must be unique for each request.
    And the redirect URL will be:

    https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID&state=$RANDOM_ID&redirect_uri=$REDIRECT_URL

    Example:

    https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID&state=ABC1234&redirect_uri=$REDIRECT_URL
  3. Once the user logs in, they will be redirected to the authorization page of the application. There you will be presented with all the requested permits.

    Once the permissions are granted, the user will be redirected to the REDIRECT URI configured in the application with the corresponding access token:
  4. http://YOUR_REDIRECT_URI?code=SERVER_GENERATED_AUTHORIZATION_CODE

    If in the previous step you had incorporated the state parameter, you will receive the authorization code and also the secure identifier in the specified return URL:

    http://YOUR_REDIRECT_URI?code=$SERVER_GENERATED_AUTHORIZATION_CODE&state=$RANDOM_ID

    Example:

    http://YOUR_REDIRECT_URI?code=$SERVER_GENERATED_AUTHORIZATION_CODE&state=ABC1234

    Remember to check that value to make sure that the response belongs to a request started by your application.
    From Mercado Libre we not validate this field.


  5. The authorization code is used to exchange it for an access token.
  6. You must perform a POST sending the parameters by BODY:

curl -X POST \
-H 'accept: application/json' \
-H 'content-type: application/x-www-form-urlencoded' \
'https://api.mercadolibre.com/oauth/token' \
-d 'grant_type=authorization_code' \
-d 'client_id=$APP_ID' \
-d 'client_secret=$SECRET_KEY' \
-d 'code=$SERVER_GENERATED_AUTHORIZATION_CODE' \
-d 'redirect_uri=$REDIRECT_URI'

Response:

{
    "access_token": "APP_USR-123456-090515-8cc4448aac10d5105474e1351-1234567",
    "token_type": "bearer",
    "expires_in": 10800,
    "scope": "offline_access read write",
    "user_id":1234567,
    "refresh_token": "TG-5b9032b4e23464aed1f959f-1234567"
}

Parameters

grant_type: authorization_code – it shows that the desired operation is to exchange the “code” for an access token.
client_id: is the APP ID of the application that you created.
client_secret: Secret Key generated when the app was created.
code: The authorization code obtained in the previous step.
redirect_uri: Redirect URI set for your application or one of the allowed domains.
Done! You can now use the access token to make requests to our API and obtain access to the private resources of the user.


Refresh token

Keep in mind that the access token will be valid for a period of 6 hours from the moment it was generated. To ensure you can work for an extended period of time and avoid the need to constantly request the user to log in again to generate a new token, we provide the solution to work with a refresh token.

Important:
For that, the application must have the option offline_access selected.

Every time you make the call to exchange the code for an access token, you will also get a refresh_token, that you will have to save to exchange it for a new access token once it expires.
To renew your access token you must make the following request:

curl -X POST \
-H 'accept: application/json' \
-H 'content-type: application/x-www-form-urlencoded' \
'https://api.mercadolibre.com/oauth/token' \
-d 'grant_type=refresh_token' \
-d 'client_id=$APP_ID' \
-d 'client_secret=$SECRET_KEY' \
-d 'refresh_token=$REFRESH_TOKEN'

Parameters

grant_type: refresh_token It shows that the desired operation is to refresh a token.
refresh_token: Refresh token from the approval step previously saved.
client_id: Is the APP ID of the application that you created.
client_secret: Secret Key generated when the app was created.

Response:

{
    "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"
}

The response includes a new access token which is valid for 6 more hours and a new REFRESH_TOKEN that you will need to save to use each time it expires.

Important:
- We only allow using the last REFRESH_TOKEN generated for the exchange.
- To optimize the processes of your development, we suggest you to renew your access token only when it expires.

Error codes reference

invalid_client: Invalid client_id and/or client_secret provided.
invalid_grant: he provided authorization grant is invalid, expired or revoked; the client_id or redirect uri do not match the original.
invalid_scope: The requested scope is invalid, unknown or malformed. The values allowed for parameter scope are: “offline_access”, “write”, “read”.
invalid_request: The request is missing a required parameter, includes an unsupported parameter or parameter value, there is some duplicated value or is otherwise malformed.
unsupported_grant_type: The values allowed for grant_type are “authorization_code” or “refresh_token”.
forbidden: The call is not authorized to access this resource. It could be possibly using the token of another user.


Next: Start testing.