# 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

| Recurso | URL |
|  --- | --- |
| **URL de Autorização** | `https://auth.contaazul.com/oauth2/authorize` |
| **URL para Token** | `https://auth.contaazul.com/oauth2/token` |
| **Scopes** | `openid profile aws.cognito.signin.user.admin` |


## 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):


```bash
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:


```bash
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"
```

- `client_id` e `client_secret`: obtidos no **Gerenciador de Aplicações**.
- O code em Base64 pode ser gerado clicando [aqui](https://www.base64encode.org/) e informando o conteúdo nesse formato: `SEU_CLIENT_ID:SEU_CLIENT_SECRET`


### Exemplo de resposta:


```json
{
  "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` - **tempo em segundos**), você deve renová-lo:


```bash
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=refresh_token" \
--data-urlencode "refresh_token=REFRESH_TOKEN_GERADO"
```

### Exemplo de resposta:


```json
{
  "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`):


```bash
curl -X GET https://api-v2.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.