Authentication and Authorization

Send access token by header

curl -H 'Authorization: Bearer APP_USR-12345678-031820-X-12345678'

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.

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.

The operation protocol is called Grant Types, and the one used is The Authorization Code Grant Type (Server Side).

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:

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:

1. Performing the authorization

1.1. Authenticate yourself with your Mercado Libre username:

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

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.

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. It must be exact to the one you configured and cannot have variable information.
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

A proper use for the state parameter is to send a state that you need to know when the URL set in the redirect_uri is called. Remember that the redirect_uri must be a static URL, so if you are considering sending parameters on this URL use the state parameter to send this information, otherwise your request will fail because the redirect_uri does not exactly match the one configured in your application.

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.

The redirect_uri has to match exactly what was entered when the application was created to avoid getting the following error, cannot contain variable information:

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

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

1.4. If you get the error message: Sorry, the application cannot connect to your account. The following considerations must be made:

1. 1. The redirect_uri must match exactly what is registered in your application settings to avoid access errors; the url cannot contain variable information.

2. 2. Validate that the appid token and grant are valid.

3. 3. Make sure the seller is logging in with the main account and not a collaborator.

4. 4. Validate that the seller has the correct KYC and that the seller is not blocked for non-compliance with policies.

2. 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: the redirect URI configured for your application cannot have variable information.

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.

3. 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. Also, remember that the refresh_token is for one-time use only and you will receive a new one at each token update process.

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.

Error codes reference

invalid_client: invalid client_id and/or client_secret provided.
invalid_grant: the 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 request is not authorized to access this resource. It could be possibly using the token of another user.

Error Invalid Grant

In the flow to refresh token or authorization code it is possible to get the error invalid_grant with the message "Error validating grant. Your refresh token or authorization code may be expired or has already been used."

{
    "error_description": "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.

Siguiente: Consulta API Docs.