Após a etapa inicial, onde o cliente Conta Azul concede permissão à sua aplicação e você recebe um código de autorização, o próximo passo crucial no fluxo do OAuth 2.0 é trocar esse código por um token de acesso (access_token). É esse access_token que sua aplicação usará para acessar os recursos protegidos do cliente Conta Azul por meio da API.
Nosso Endpoint de requisição do token de acesso: https://auth.contaazul.com/oauth2/token
Nesta fase, sua aplicação faz uma requisição diretamente para o servidor de autorização (e não para o navegador) para trocar o código temporário por um token de acesso de longa duração. É um processo seguro e servidor-para-servidor, o que significa que as credenciais sensíveis da sua aplicação (client_secret) não são expostas ao usuário final.
Exemplo de Requisição API (usando cURL):
curl -X POST https://auth.contaazul.com/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic BASE64(SEU_CLIENT_ID:SEU_CLIENT_SECRET)
--data-urlencode "client_id=SEU_CLIENT_ID" \
--data-urlencode "client_secret=SEU_CLIENT_SECRET" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code=CODIGO_AUTORIZACAO" \
--data-urlencode "redirect_uri=SUA_URL_REDIRECIONAMENTO"Essa requisição POST contém vários parâmetros que informam ao servidor de autorização sobre sua solicitação:
| Parâmetro | Valor | Valor Fixo? | Finalidade | Detalhes |
|---|---|---|---|---|
| Authorization | Basic BASE64(client_id:client_secre) | Não | Este é um cabeçalho HTTP necessário. Ele contém seu client_id e client_secret combinados (client_id:client_secret) e codificados em Base64 | Para mais detalhes sobre a codificação em Base64, consulte o guia FAQ dessa documentação |
| client_id | Disponível nos detalhes da sua integração no Portal do Desenvolvedor | Não | Identificador único do aplicativo | |
| client_secret | Disponível nos detalhes da sua integração no Portal do Desenvolvedor | Não | Identificador que comprova a identidade do aplicativo | |
| grant_type | Authorization_code | Sim | Indica a troca de um código de autorização por um token de acesso | |
| code | Código de autorização obtido na etapa anterior do fluxo OAuth 2.0 | Não | Usado para validar a requisição e garantir que a troca está ocorrendo para o aplicativo correto | É crucial que o código de autorização seja exatamente o mesmo recebido na etapa anterior e que seja usado dentro do seu prazo de validade (3 minutos) |
| redirect_uri | Disponível nos detalhes da sua integração no Portal do Desenvolvedor | Não | Validar que a requisição de troca está sendo feita pela mesma aplicação cliente que iniciou o processo | É crucial que esta URL seja exatamente igual à URL informada na integração pelo Portal do Desenvolvedor, ao contrário o servidor irá rejeitar a requisição de troca do token |
Se a requisição for bem sucedida, o servidor de autorização responderá com um JSON contendo dois tokens importantes: access_token e o refresh_token:
{
"access_token": "ACCESS_TOKEN_GERADO",
"expires_in": 3600,
"refresh_token": "REFRESH_TOKEN_GERADO",
"token_type": "Bearer"
}É necessário salvar cada um desses tokens de forma segura, pois eles são importantes para os próximos passos do fluxo OAuth 2.0. Abaixo está algumas informações importantes:
| Token | Validade | Finalidade |
|---|---|---|
| access_token | 3600 segundos (1 hora) | Este token é a credencial da sua integração para fazer requisições autenticadas e autorizadas aos recursos da API |
| refresh_token | 5 anos ou até próxima renovação do access_token | Este token é de uso mais prolongado e seguro. Usado para renovar o access_token quando ele expira. Deve ser armazenado de forma segura. Deve-se armazenar um novo refresh_token em toda requisição de renovação do access_token |
Com o access_token é possível fazer chamadas autenticadas à API da Conta Azul, acessando os dados do cliente Conta Azul vinculado ao seu aplicativo. Quando o access_token expirar, você usará o refresh_token para obter um novo, garantindo que a conexão com a API possa ser mantida sem a necessidade de uma nova autenticação.
Para utilizar o access_token consulte o passo “Fazendo Chamadas à API com o Access Token” e para renová-lo consulte o passo “Renovando seu Access Token (Essencial para Acesso Contínuo)".