Obter Access Token
Saiba como utilizar os fluxos, tambĂ©m conhecidos como grant types, para obter um Access Token e acessar os dados expostos por uma API. A existĂȘncia desses fluxos surge para responder a todos os cenĂĄrios de negĂłcios que podem surgir no consumo de APIs com base no tipo de aplicação consumidora, seu grau de confiança e como Ă© a interação do usuĂĄrio no processo.
Os fluxos de acesso disponĂveis para geração do Access Token sĂŁo:
- Authorization code: quando se for usar as credenciais para acessar um recurso em nome de terceiros.
- Client credentials: quando se for usar as credenciais para acessar um recurso em nome prĂłprio.
Authorization code
O fluxo se caracteriza pela intervenção do vendedor para autorizar de forma explĂcita o acesso aos seus dados por parte da aplicação e pelo uso de um cĂłdigo concedido pelo servidor de autenticação para que a aplicação possa obter um Access Token e um refresh token associado.
Por ser um fluxo baseado em redirecionamento, vocĂȘ deve ser capaz de permitir interação com o navegador do vendedor e de receber o request
atravĂ©s do redirecionamento por parte do servidor de autorização. Neste fluxo, a aplicação solicita ao vendedor o consentimento expresso para acessar os dados atravĂ©s da abertura de uma pĂĄgina web que deixa explĂcito os scopes aos quais se estĂĄ solicitando acesso.
Uma vez permitido o acesso, o servidor gera um código de acesso que mediante um redirecionamento chega à aplicação. Nesta etapa, a aplicação solicita acesso ao servidor de autenticação enviando o código obtido e os dados da aplicação. Feito isso, o servidor concede o Access Token e o refresh token à aplicação.
Veja abaixo como configurar o protocolo PKCE (um protocolo de segurança não obrigatório que oferece uma camada extra de proteção, por isso é recomendado) e, em seguida, gerar o Access Token.
Configurar PKCE
O PKCE (Proof Key for Code Exchange) Ă© um protocolo de segurança usado com OAuth para proteger contra ataques de cĂłdigo malicioso durante a troca de cĂłdigos de autorização por Access Token. Ele adiciona uma camada extra de segurança gerando um verifier que Ă© transformado em um challenge para garantir que mesmo se o cĂłdigo de autorização for interceptado, ele nĂŁo seja Ăștil sem o verifier original.
Siga os passos abaixo para habilitar e configurar o uso o fluxo de código de autorização com o PKCE.
- Primeiramente, na tela de Detalhes de aplicação, clique em Editar e habilite o uso o fluxo de código de autorização com o PKCE. Com o campo habilitado, o Mercado Pago passarå a requerer como obrigatórios os campos
code_challenge
ecode_method
nas requisiçÔes de OAuth. - Os campos exigidos poderão ser gerados de vårias formas, com desenvolvimento próprio ou uso de SDKs. Siga os passos necessårios descritos nesta documentação oficial para gerar os campos que serão requeridos.
- ApĂłs gerar e criptografar os campos, serĂĄ necessĂĄrio enviar os respectivos cĂłdigos ao Mercado Pago. Para isso, envie via
query_params
utilizando a URL de autenticação abaixo.
URL
https://auth.mercadopago.com/authorization?response_type=code&client_id=$APP_ID`redirect_uri=$YOUR_URL&code_challenge=$CODE_CHALLENGE&code_challenge_method=$CODE_METHOD
- Redirect_uri: URL informada no campo "Redirect URL" da sua aplicação.
- Code_verifier: cĂłdigo que deverĂĄ ser gerado, respeitando seus requisitos para funcionamento, sendo eles: uma sequĂȘncia aleatĂłria de caracteres que tenham entre 43-128 caracteres, com letras maiĂșsculas, minĂșsculas, nĂșmeros e alguns caracteres especiais. Por exemplo: 47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU.
- Code_challenge: em seguida, Ă© necessĂĄrio criar um
code_challenge
a partir docode_verifier
usando uma das seguintes transformaçÔes:- Se for possĂvel utilizar S256, serĂĄ necessĂĄrio usar essa opção transformando o
code_verifier
em umcode_challenge
através de uma codificaçãoBASE64URL
apĂłs aplicar a função "SHA256". - Se nĂŁo for possĂvel usar S256 por algum motivo tĂ©cnico e o servidor suportar o mĂ©todo Plain, Ă© possĂvel definir o
code_challenge
igual aocode_verifier
.
- Se for possĂvel utilizar S256, serĂĄ necessĂĄrio usar essa opção transformando o
- Code_challenge_method: é o método utilizado para gerar o
code_challenge
, conforme descrito no item acima. Este campo poderå ser, por exemplo, S256 ou Plain, de acordo com a codificação selecionada na etapa decode_challenge
.
- Tendo enviado os cĂłdigos corretamente ao Mercado Pago, vocĂȘ obterĂĄ a autorização necessĂĄria (
code_verifier
) para obter o Access Token e realizar a verificação por PKCE nas transaçÔes feitas com OAuth.
Obter token
O Access Token Ă© o cĂłdigo utilizado em diferentes requests pĂșblicos para acessar um recurso protegido. Nesse fluxo, ele representa uma autorização concedida por um vendedor a uma aplicação do cliente, contendo scopes e um tempo de validade limitado para o acesso. Siga os passos abaixo para obtĂȘ-lo.
Edite sua aplicação para conter suas URLs de redirecionamento. Veja Editar aplicação.
Envie a URL de autenticação para o vendedor cuja conta vocĂȘ deseja vincular Ă sua com os seguintes campos:
Authentication_URL
https://auth.mercadopago.com/authorization?client_id=APP_ID&response_type=code&platform_id=mp&state=RANDOM_ID&redirect_uri=https://www.redirect-url.com
Campo Descrição Client_id Substitua o valor "APP_ID" com a nĂșmero da sua aplicação. Veja Detalhes da aplicação para mais informaçÔes. State Substitua o valor "RANDOM_ID" por um identificador que seja Ășnico para cada tentativa e que nĂŁo inclua informaçÔes sensĂveis, de forma que vocĂȘ consiga identificar de quem Ă© o cĂłdigo recebido. Isso garantirĂĄ que a resposta pertença a uma solicitação iniciada pelo mesmo aplicativo. Redirect_uri Adicione a URL informada no campo "URLs de redirecionamento" da sua aplicação. Certifique-se de que o redirect_uri seja uma URL estĂĄtica. Veja Detalhes da aplicação para mais informaçÔes. Se desejar enviar parĂąmetros adicionais emredirect_uri
, utilize o parĂąmetrostate
para incluir essas informaçÔes. Caso contrårio, a chamada receberå uma resposta de erro se a URL não corresponder exatamente à configuração do aplicativo.Aguarde o vendedor acessar a URL e permitir o acesso. Ao acessar a URL o vendedor serå direcionado para o Mercado Pago e deverå realizar o login na conta dele para realizar a autorização.
Verifique na URL de redirecionamento do seu servidor o código de autorização retornado no parùmetro code.
Redirect_URL
https://www.redirect-url.com?code=CODE&state=RANDOM_ID
Envie as suas credenciais (
client_id
eclient_secret
), o código de autorização (code
) retornado e, caso tenha configurado o PKCE, ocode_verifier
ao endpoint /oauth/token para receber como resposta o Access Token.
<?php
$client = new OauthClient();
$request = new OAuthCreateRequest();
$request->client_secret = "CLIENT_SECRET";
$request->client_id = "CLIENT_ID";
$request->code = "CODE";
$request->redirect_uri = "REDIRECT_URI";
$client->create($request);
?>
OauthClient client = new OauthClient();
String authorizationCode = "TG-XXXXXXXX-241983636";
client.createCredential(authorizationCode, null);
const client = new MercadoPagoConfig({ accessToken: 'access_token', options: { timeout: 5000 } });
const oauth = new OAuth(client);
oauth.create({
'client_secret': 'your-client-secret',
'client_id': 'your-client-id',
'code': 'return-of-getAuthorizationURL-function',
'redirect_uri': 'redirect-uri'
}).then((result) => console.log(result))
.catch((error) => console.log(error));
curl -X POST \
'https://api.mercadopago.com/oauth/token'\
-H 'Content-Type: application/json' \
-d '{
"client_id": "client_id",
"client_secret": "client_secret",
"code": "TG-XXXXXXXX-241983636",
"grant_type": "authorization_code",
"redirect_uri": "APP_USR-4934588586838432-XXXXXXXX-241983636",
"refresh_token": "TG-XXXXXXXX-241983636",
"test_token": "false"
}'
test_token
com valor true
.Client credentials
Este fluxo é utilizado quando as aplicaçÔes solicitam um Access Token usando apenas as suas próprias credenciais e para acessar seus próprios recursos. A principal diferença em relação aos outros fluxos é que o usuårio não interage no processo e, consequentemente, a aplicação não pode atuar em nome do usuårio.
Obter token
O Access Token Ă© o cĂłdigo utilizado em diferentes requests pĂșblicos para acessar um recurso protegido. Neste fluxo, obtĂ©m-se o Access Token sem interação do usuĂĄrio e apenas para acessar seus prĂłprios recursos.
Siga os passos abaixo para obtĂȘ-lo.
- Envie as suas credenciais (
client_id
eclient_secret
) ao endpoint /oauth/token com o cĂłdigoclient_credentials
no parĂąmetrogrant_type
para receber uma nova resposta com oaccess_token
. - Atualize a aplicação com o Access Token recebido na resposta.
<?php
$client = new OauthClient();
$request = new OAuthCreateRequest();
$request->client_secret = "CLIENT_SECRET";
$request->client_id = "CLIENT_ID";
$client->create($request);
?>
const client = new MercadoPagoConfig({ accessToken: 'access_token', options: { timeout: 5000 } });
const oauth = new OAuth(client);
oauth.create({
'client_secret': 'your-client-secret',
'client_id': 'your-client-id',
}).then((result) => console.log(result))
.catch((error) => console.log(error));
curl -X POST \
'https://api.mercadopago.com/oauth/token'\
-H 'Content-Type: application/json' \
-d '{
"client_id": "client_id",
"client_secret": "client_secret",
"grant_type": "client_credentials",
}'