Authentication and Authorization

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.

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 get 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, integrity and availability.

Server side flow

In Mercado Libre we are using Authorization Code Grant Type. Is better suited for applications executing the server-side code such as, applications developed in Java, Grails, Go, etc. The process you will be performing is as follows:

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.

Get access token

1. Login and Authenticate with your Mercado Libre account
Notes:
- You can use test users.
- 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 an 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.
• If you do not use the application with any request at https://api.mercadolibre.com/ for 4 months.


2. Place the URL in your browser to get authorization

APP_ID: id of application.
YOUR_URL: the redirect URI that you add when create the app

https://global-selling.mercadolibre.com/authorization?response_type=code&client_id=$APP_ID&redirect_uri=$YOUR_URL

You will receive the following parameters are optional and only apply if the app has enabled the PKCE flow (Proof Key for Code Exchange):
code_challenge: verification code generated from code_verifier and encrypted with 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 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 have to match with what was loaded when your app ID was created to avoid errors:




3. Users will be redirected to the following screen to accept associate the application with their account

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

http://YOUR_REDIRECT_URI?code=$TG-CODE

Use the TG-Code to get the access_token in the next step.



4. Changing the code for access token

Make POST request sending:
grant_type: authorization_code, it shows that the desired operation is to exchange the “code” for an access_token.
client_id: application ID.
client_secret: Secret Key generated when the app was created.
code: authorization TG-code obtained in the previous step.
redirect_uri: Redirect URI set for your application.





curl -X POST -H 'accept: application/json' -H 'content-type: application/x-www-form-urlencoded' https://api.mercadolibre.com/oauth/token?grant_type=authorization_code&client_id=$APP_ID&client_secret=$CLIENT_SECRET&code=$TG_CODE&redirect_uri=$REDIRECT_URL

Response:

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

The access_token is valid for 6 hours from the moment it was generated. To get more time, we recommend get refresh token (new access_token which is valid for 6 months). Save it to use each time it expires. We only allow using the last refresh token generated. Additionally, remember that the refresh token is single-use, and you will receive a new one with each token refresh process.



5. Refresh token



grant_type: refresh_token, it shows that the desired operation is to exchange the “code” for a new access_token.
client_id: application ID.
client_secret: Secret Key generated when the app was created.
refresh_token: refresh_token obteined getting access token previous.





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

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

Error

Status	Error
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 call is not authorized to access this resource. It could be possibly using the token of another user.

Revokes types

• 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 Application's 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.

Next: Users.