• API Docs
  • Getting started
  • Authentication and Authorization
Last update 02/12/2022

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.


Send access token by header

For security, you must send the access token by header every time you make calls to the API. The header for the Authorization is:
curl -H 'Authorization: Bearer APP_USR-12345678-031820-X-12345678'
And for example, making a GET to the /users/me resource it would be:
curl -H 'Authorization: Bearer APP_USR-12345678-031820-X-12345678' \
https://api.mercadolibre.com/users/me

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 Mercado Libre we authenticate ourselves by entering our username and password. These are the steps to follow:


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 Java, Grails, Go, etc.


To sum up, the process you will be doing is the following:

flujo_serverside_eng

References

  1. Redirects the app to Mercado Libre.
  2. You do not have to worry about the authentication of the users of Mercado Libre, our platform will take care of it!
  3. Authorization site.
  4. POST to exchange the authorization code for an access token.
  5. The Mercado Libre 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


The steps to follow are:


Performing the authorization

1. Authenticate yourself with your Mercado Libre username:

Notes:
- If you want to use a test user, enter here.
- Remember that 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.

2. Put the following URL in your browser window to get authorization:

https://auth.mercadolibre.com.ar/authorization?response_type=code&client_id=$APP_ID&redirect_uri=$YOUR_URL&code_challenge=$CODE_CHALLENGE&code_challenge_method=$CODE_METHOD

Parameters

Response_type: Sending the value code you will obtain an access token that will allow you to interact with Mercado Libre.
Redirect_URI: The attribute YOUR_URL is completed with the value added when the app was created.


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.

State: In case you do not have a secure random identifier, you can create it using SecureRandom and it must be unique for each request. 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

The following parameters are optional and only apply if the application has PKCE (Proof Key for Code Exchange) flow enabled. Hhowever, when this option is activated, sending the field becomes mandatory:

code_challenge:: ódigo de verificación generado a partir de code_verifier y cifrado con code_challenge_method.

code_challenge_method:: method used to generate the code challenge. The following values are currently supported:

  • S256: specifies that the code_challenge is encrypted using the SHA-256 encryption algorithm.
  • plain: the same code_verifier is sent as code_challenge. For security reasons it is not recommended to use this method.

3. In the example we use the URL for Argentina (MLA) 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.


4. 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.


Nota:
We add the DPP information (partner level) to seller with the information about the application is certified or not.

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

https://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.

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

Example:

https://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.


Nota:
- Consider that if the user is an operator/collaborator, you will NOT be able to grant the application. It will return the error invalid_operator_user_id.


Changing code for a token

The authorization code is used to exchange it for an access token.


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' \
-d 'code_verifier=$CODE_VERIFIER'

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

Done! You can now use the access token to make requests to our API and obtain access to the private resources of the user.


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.


The following parameters are optional and only apply if the application has PKCE (Proof Key for Code Exchange) flow enabled.

code_verifier: random character sequence with which the code_challenge was generated. This will be used to verify and validate the request.


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.


Error Invalid Grant

During the flow get the upgrade or authorization code, you may get the invalid_grant error with the message Error validating grant. "Your authorization code or upgrade code may have expired or has already been used."

{
    "message": "Error validating grant. Your authorization code or refresh token may be expired or it was already used",
    "error": "invalid_grant",
    "status": 400,
    "cause": []
}

This message indicates that the authorization_code or refresh_token do not exist, or have been deleted. Some reasons are:

  • Expiration Tim: after the refresh_token expires (6 months), it will automatically expire, and you will need to re-flow to get a new refresh_token.
  • Revocation of authorization: by revoking the authorization between the seller's account and your application (either by the integrator or the seller), the access_token and refresh_token will be invalidated. You can check the users who have no grant with your application from the "Manage Permissions" option (in My Applications dashboard), or by using the call to access the users who have granted licenses to your application.
  • Internal revocation: there are some internal flows that cause users' credentials to be deleted, preventing integrators from being able to continue working on behalf of vendors; in these cases, it is necessary to complete the authorization/authentication flow again. These flows are triggered primarily by deletion of user sections. The reasons are various, but the most common are password change, device unlinkage, or fraud. Learn how to revoke a user's authorization to your application.
Important:
Keep in mind that for this last stream, we have only detailed some examples, not all available cases.

Siguiente: Consulta API Docs.