> For the complete documentation index, see [llms.txt](https://docs.autentique.com.br/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autentique.com.br/api/2/integracao/oauth2/erros-e-seguranca-do-oauth.md). # Erros e segurança do OAuth Erros OAuth podem acontecer durante a autorização, na troca ou renovação dos tokens e nas chamadas à API GraphQL. Não tente corrigir um erro reutilizando códigos, sessões ou tokens antigos. Quando a tentativa não puder ser recuperada com segurança, inicie uma nova autorização. ### Erros durante a autorização Esses erros chegam à URL de redirecionamento. | Situação | O que fazer | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `error=access_denied` | O usuário pode ter negado o acesso, desmarcado todas as permissões ou recebido uma solicitação sem escopos válidos. Mostre que a conexão não foi concluída e ofereça uma nova tentativa somente se ele quiser continuar. | | `error=login_required` | Pode acontecer quando a solicitação usa `prompt=none`. Este parâmetro não é suportado no momento. Inicie uma autorização normal no navegador, sem `prompt=none`. | | `error=invalid_scope` | Confira se os escopos existem, estão habilitados no aplicativo e foram enviados separados por espaços. | | `error=invalid_client` | Confira o Client ID, se o aplicativo continua ativo e se a URL de redirecionamento corresponde exatamente à cadastrada. | | `state` ausente ou diferente | Descarte o callback e a sessão de autorização. Não use o código recebido. | Receber menos permissões do que as solicitadas não é necessariamente um erro. O usuário pode conceder apenas um subconjunto. Sua integração deve funcionar dentro do acesso realmente concedido. ### Erros na troca do código O endpoint `/oauth/token` retorna um erro OAuth e, em alguns casos, um `hint` com mais detalhes. | Situação | O que fazer | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | | `error=invalid_client` ou HTTP 401 | Confira o Client ID, o Client Secret e se o aplicativo está ativo. | | `error=invalid_request` com indicação de URL inválida | Envie exatamente a mesma `redirect_uri` cadastrada e usada no início da autorização. | | Código ausente, expirado, revogado ou reutilizado | Inicie uma nova autorização. Códigos de autorização são temporários e de uso único. | | Código emitido para outro cliente | Use as credenciais do mesmo aplicativo que iniciou a autorização. | | `code_verifier` ausente ou malformado | Envie o verificador da mesma tentativa, com 43 a 128 caracteres. | | `error=invalid_grant` com falha na verificação de PKCE | O `code_verifier` não corresponde ao `code_challenge`. Descarte a tentativa e inicie uma nova autorização. | ### Erros na renovação Se o `refresh_token` for rejeitado: 1. confirme que a integração está usando o valor mais recente; 2. verifique se outra requisição já renovou os tokens; 3. interrompa novas tentativas automáticas com o mesmo valor; 4. peça uma nova autorização ao usuário se o token expirou ou foi revogado. Não repita indefinidamente uma renovação que retornou erro. Isso não recupera o token e pode esconder um problema de concorrência ou revogação. ### Erros na API GraphQL | Resposta | Possível causa | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP 401 com `{"message":"unauthorized"}` | O `access_token` está ausente, inválido, expirado ou foi revogado. Tente renovar os tokens. Se a renovação falhar, solicite uma nova autorização. | | HTTP 200 com `errors[].message="Unauthorized"` | O token foi aceito, mas a permissão necessária não foi concedida ou a operação não aceita OAuth. Confira o escopo da operação. | Como o GraphQL pode retornar erros com HTTP 200, verifique também o campo `errors` da resposta. ### Checklist de segurança Antes de publicar a integração, confirme: * [ ] O Client Secret existe somente no backend. * [ ] As URLs de redirecionamento usam HTTPS em produção. * [ ] A URL recebida e enviada é comparada exatamente com a cadastrada. * [ ] Cada autorização cria novos valores de `state` e PKCE. * [ ] O callback rejeita `state` ausente ou diferente. * [ ] O código de autorização nunca é reutilizado. * [ ] A integração solicita somente as permissões necessárias. * [ ] Tokens são armazenados de forma protegida e nunca aparecem em URLs ou logs. * [ ] A renovação salva o novo `refresh_token` antes de liberar outras requisições. * [ ] A integração consegue revogar e apagar acessos que não são mais necessários. ### Em caso de vazamento Se houver suspeita de vazamento do Client Secret: 1. crie um novo aplicativo OAuth; 2. atualize a integração com as novas credenciais; 3. confirme que o novo aplicativo está funcionando; 4. revogue o aplicativo comprometido. A revogação desativa o aplicativo e seus tokens. Revogue também um aplicativo quando: * a integração for descontinuada; * ela não precisar mais acessar as contas dos usuários; * houver comportamento inesperado que indique uso indevido das credenciais ou tokens. Depois de conter o incidente, remova credenciais de logs, repositórios e ferramentas em que elas possam ter sido registradas e revise como o vazamento aconteceu.