Autenticação na API da Conta Azul

Este guia detalha o processo de autenticação utilizando o fluxo Authorization Code do protocolo OAuth 2.0 para integração com a API da Conta Azul, permitindo acesso seguro aos recursos disponíveis.

URLs e Parâmetros Importantes

Visão Geral do Fluxo OAuth 2.0

O fluxo Authorization Code permite que seu aplicativo obtenha acesso seguro aos recursos da Conta Azul sem necessidade de expor as credenciais sensíveis do usuário.

Etapas principais:

1. Solicitar um código de autorização
2. Trocar o código recebido por um access_token
3. Usar o access_token para acessar recursos protegidos
4. Renovar o access_token utilizando um refresh_token

1. Solicitação do Código de Autorização

Faça uma requisição GET inicial com cURL ou diretamente no navegador (durante o desenvolvimento):

curl -X GET "https://auth.contaazul.com/oauth2/authorize?response_type=code&client_id=SEU_CLIENT_ID&redirect_uri=SUA_URL_REDIRECIONAMENTO&state=ESTADO&scope=openid+profile+aws.cognito.signin.user.admin"

Parâmetros obrigatórios:

• response_type: valor fixo code.
• client_id: obtido no Gerenciador de Aplicações da Conta Azul.
• redirect_uri: exatamente igual à informada ao criar a aplicação no Gerenciador de Aplicações.
• state: valor aleatório único, usado para segurança.
• scope: valor fixo conforme descrito acima.

Após a autorização do usuário, haverá um redirecionamento automático para a URL configurada contendo um code:

https://SUA_URL_REDIRECIONAMENTO?code=CODIGO_AUTORIZACAO&state=ESTADO

2. Troca do Código pelo Token de Acesso (access_token)

Troque o código obtido na etapa anterior por um access_token, para essa chamada precisará ser adicionado no cabeçalho da requisição a autorização a autorização do tipo BASIC com o SEU_CLIENT_ID e o SEU_CLIENT_SECRET codificado em Base64, usando o 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)
-d "client_id=SEU_CLIENT_ID" \
-d "client_secret=SEU_CLIENT_SECRET" \
-d "grant_type=authorization_code" \
-d "code=CODIGO_AUTORIZACAO" \
-d "redirect_uri=SUA_URL_REDIRECIONAMENTO"

• client_id e client_secret: obtidos no Gerenciador de Aplicações.
• O code em Base64 pode ser gerado clicando aqui e informando o conteúdo nesse formato: SEU_CLIENT_ID:SEU_CLIENT_SECRET

Exemplo de resposta:

{
  "access_token": "ACCESS_TOKEN_GERADO",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN_GERADO",
  "token_type": "Bearer"
}

Explicação sobre os tokens:

• access_token: usado para autenticar chamadas futuras à API.
• refresh_token: usado para renovar o access_token após expiração.

3. Renovação do access_token usando refresh_token

Quando seu access_token expirar (após o tempo informado em expires_in), você deve renová-lo:

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)
-d "client_id=SEU_CLIENT_ID" \
-d "client_secret=SEU_CLIENT_SECRET" \
-d "grant_type=refresh_token" \
-d "refresh_token=REFRESH_TOKEN_GERADO"

Exemplo de resposta:

{
  "access_token": "NOVO_ACCESS_TOKEN",
  "expires_in": 3600,
  "refresh_token": "NOVO_REFRESH_TOKEN",
  "token_type": "Bearer"
}

Atenção: Sempre guarde o novo refresh_token, pois ele também pode mudar após cada renovação.

4. Usando o access_token em Chamadas da API

Para acessar qualquer recurso protegido da API Conta Azul, envie o access_token no cabeçalho da requisição (Authorization):

curl -X GET https://api-public.contaazul.com/v1/exemplo/recurso \
-H "Authorization: Bearer ACCESS_TOKEN_GERADO"

🎉 Parabéns! Você agora está apto a integrar e consumir a API da Conta Azul de forma segura utilizando OAuth 2.0.