O access_token é uma credencial temporária, projetada para expirar após 1 hora. Para garantir que sua integração continue funcionando sem interrupções e sem precisar passar por todo o processo de autorização novamente, o protocolo OAuth 2.0 oferece um mecanismo de renovação usando o refresh_token.
Você deve renovar o access_token quando ele expirar. Isso geralmente é sinalizado por um erro 401 Unauthorized da API. Em vez de obrigar o usuário a passar por todo o processo de autorização novamente, sua aplicação pode usar o refresh_token - obtido na primeira troca - para fazer uma requisição segura, servidor-para-servidor, e obter um novo access_token. A requisição de renovação também retorna um novo refresh_token, que sua aplicação deve armazenar para futuras renovações.
Use o refresh_token, juntamente com seu client_id e client_secret (disponíveis nos detalhes da sua integração no Portal do Desenvolvedor), para solicitar um novo access_token ao nosso endpoint.
https://auth.contaazul.com/oauth2/token
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"Essa requisição POST contém vários parâmetros que informam ao servidor de autorização sobre sua solicitação:
| Parâmetros | Valor | Valor Fixo? | Finalidade | Descrição |
|---|---|---|---|---|
| grant_type | refresh_token | Sim | Indica que você está solicitando um novo access_token usando um refresh_token | |
| 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 | |
| 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 desta documentação |
| REFRESH_TOKEN_GERADO | refresh_token obtido na etapa anterior do fluxo OAuth 2.0 | Não | permite que sua aplicação obtenha um novo access_token após o token original expirar | É crucial que o refresh_token seja exatamente o mesmo recebido na etapa anterior |
Se a renovação for bem-sucedida, o servidor responderá com um novo conjunto de tokens:
{
"access_token": "NOVO_ACCESS_TOKEN",
"expires_in": 3600,
"refresh_token": "NOVO_REFRESH_TOKEN",
"token_type": "Bearer"
}É necessário salvar cada um desses tokens de forma segura. Abaixo está algumas informações importantes:
| Token | Validade | Finalidade |
|---|---|---|
| access_token | 3600 segundos (1 hora) | Este é o novo token de acesso que sua aplicação deve usar a partir de agora para as chamadas à API. O antigo access_token não é mais válido |
| refresh_token | 5 anos ou até próxima renovação do access_token | ⚠️ Atenção: O refresh_token muda após cada renovação. É crucial que sua aplicação sempre armazene e passe a usar o novo refresh_token recebido na resposta. Se você continuar tentando usar o refresh_token antigo, a próxima tentativa de |
O refresh_token é a chave para a experiência do usuário. Ele permite que sua aplicação mantenha o acesso à API por um longo período (até que o refresh_token também expire) sem precisar pedir pela autorização novamente. Por ser uma credencial de longa duração, ele é extremamente sensível e deve ser armazenado com o máximo de segurança possível.