Bem vindo, desenvolvedor! Nessa seção nós vamos aprender a gerar o nosso primeiro Access Token! com Authorization Code para consumir as APIs do BTG PACTUAL EMPRESAS! Espero que você já tenha criado o seu primeiro Aplicativo para que possa acompanhar o conteúdo de forma satisfatória! =)

O Access Token obtido por meio do Auth Code Flow dá acesso às informações que o usuário concordar compartilhar, portanto, ele é token NECESSÁRIO para consumir as APIs de banking!

Este tutorial é válido para ambos os ambientes de Sandbox e Produção então não se preocupe caso ainda não tenha tido seu Aplicativo Verificado.

Segurança

Lembre-se sempre que algumas informações são confidenciais e em nenhum momento elas serão necessárias para que possamos resolver quaisquer problemas que você possa encontrar. Portanto, é extremamente importante que sempre ofusque informações como o Secret, Access Token, Client ID...

Todas as informações sensiveis neste tutorial estarão ofuscadas para a segurança de todos! =)

Área do Desenvolvedor

A nossa primeira parada é na Área do desenvolvedor, onde você irá se deparar com algo semelhante à imagem:

Aqui, nós temos alguns campos importantes:
Client ID, URIs do redirecionamento, Secret e os Escopos

Vamos definir a nossa URI de redirecionamento! Você pode ter mais de uma, então não se preocupe em ter que se prender a apenas uma.

No nosso tutorial vamos utilizar uma URI fictícia, mas no seu sistema real ela será uma URI de callback do seu sistema interno para receber o código que será gerado!

Agora que temos a nossa URI de redirecionamento, precisamos definir os escopos que o nosso Aplicativo irá pedir.

Escopos

O escopo openid é obrigatório, mas os outros você deverá escolher conforme as necessidade do seu sistema pois eles definem quais APIs o seu sistema terá acesso.

Tendo definidos os nossos escopos e nossa URI de redirecionamento, vamos começar a preparar o nosso ambiente para realizar nossas requisições!

Fluxos de autenticação

É interessante que você visite nossas páginas sobre os Fluxos que utilizaremos aqui para que entenda melhor quais são os protocolos, mas basicamente nossos servidores utilizam o Oauth2.0!

Postman

Muitas ferramentas podem ser utilizadas, desde mais genéricas como o Insomnia e Postman até ferramentas especificas como o Oauth tools. Aqui no tutorial, vou utilizar a extensão do Postman para o VS code, mas o mesmo processo pode ser feito em qualquer uma dessas ferramentas! =)
Vamos configurá-lo para atender melhor a nossa demanda?

Configurando o ambiente

Vamos criar variáveis de ambiente para facilitar o nosso processo e ao mesmo tempo facilitar a visualização de qual informação está indo onde. Eu optei por criar um ambiente chamado "Tutorial-Access_token_ambiente" e lá criei as seguinte váriaveis:

E as preenchi da seguinte forma:

base_uri: https://id.sandbox.btgpactual.com
client_id: Client Id que está na Área do Desenvolvedor
scope: escopos que selecionei na Área do Desenvolvedor, nesse caso openid
prompt: por padrão mantive login
redirect_uri: https://localhost.com a nossa URI fictícia

Nosso ambiente, então, ficou assim:

Com isso nós podemos dar inicio ao nosso fluxo!

Authorization code

Aqui é o primeiro passo para obtermos nosso tão almejado Access Token e finalmente acessar as APIs. Nessa etapa nós enviamos para o servidor de autenticação algumas informações e ele nos devolve um authorization code referente a isso!
No postman, nós montamos a URI de acordo com a descrita na nossa página sobre o fluxo de Authorization Code e ela fica da seguinte forma:

Depois disso, pegamos o cURL clicando em "code":

E colocamos no nosso navegador a url para darmos inicio no fluxo de access grant (o seu usuário que fará essa parte =) ):

É só fazer login com sua conta do BTG.

Aqui é onde aparecem os escopos que você deixou marcado e é aqui onde seus cliente escolhem quais deles aceitará. Como deixamos apenas o openid, esse é a único que aparece.

Após confirmar, você será levado para a sua redirect_uri, que será no nosso caso uma página não encontrada, porém ao olharmos na URL do navegador:

Temos o nosso Authorization Code(tudo entre "?code=" e "&"). Esse nós copiamos e poderemos dar inicio ao fluxo do Access Token.

Access Token

O Access Token obtemos ao realizar uma requisição POST enviando o Authorization Code e algumas de nossas credenciais conforme nossa página sobre o fluxo:

Depois disso, precisamos configurar o protocolo de autenticação:

Utilizamos o esquema básico de autenticação:

Username é o nosso client_id configurado no ambiente
Password é o nosso Secret que fica lá na Área do Desenvolvedor

Caso opte por fazer de maneira programática é preciso encodar em base64 uma string que consista de client_id:client_secret

Agora, configuramos o body da request:

É extremamente importante que seja enviado como form-urlencoded!
O campo code é onde colocamos o nosso Authorization code obtido anteriormente e o campo grant_type não precisamos nos preocupar, basta por conforme a documentação mostra.

Basta enviarmos a request que receberemos de volta o nosso Access Token:

E é assim, desenvolvedor, que obtemos o Access Token por meio do Authorization Code Flow!

Postman

Temos uma collection do postman com todas as requests mais utilizadas e demandadas pelos nossos clientes. Para encontra-lá basta visitar nossa página Postman Collections