OAuth 2.0

Permita que usuários autorizem sua integração a acessar a API do Autentique em nome deles.

OAuth 2.0 permite que um usuário autorize sua integração a acessar determinados dados do Autentique sem compartilhar a senha da conta.

O seu sistema pede autorização para acessar a conta do Autentique do seu usuário, enviando ele para uma página do Autentique onde ele confere as permissões solicitadas e decide o que deseja autorizar. Sua integração recebe tokens para chamar a API somente dentro das permissões concedidas. O acesso pode ser interrompido depois pela revogação do aplicativo.

Quando usar OAuth

Use OAuth quando sua integração será utilizada por outras pessoas ou organizações do Autentique.

Por exemplo, uma plataforma de gestão pode permitir que cada cliente conecte sua própria conta do Autentique. Depois da autorização, a plataforma consegue consultar ou criar documentos em nome daquele cliente, conforme as permissões concedidas.

Se você precisa integrar somente uma conta controlada por você, uma chave de API pode ser mais simples.

Forma de acesso	Indicada para
Chave de API	Integrações internas que acessam a conta à qual a chave pertence.
OAuth 2.0	Aplicativos usados por diferentes usuários, que autorizam o acesso às próprias contas.

OAuth é um protocolo de autorização. Sua integração não recebe a senha do usuário e não deve pedir que ele informe as credenciais do Autentique fora das páginas do próprio Autentique.

Como funciona

O Autentique utiliza o fluxo Authorization Code com PKCE:

1. Sua integração cria valores temporários de segurança e envia o usuário para o Autentique.

2. O usuário entra na conta, confere as permissões solicitadas e aprova ou nega o acesso.

3. O Autentique redireciona o usuário para a URL cadastrada no aplicativo.

4. Se o acesso for aprovado, sua integração recebe um código de autorização de uso único.

5. Seu backend troca esse código por um access_token e um refresh_token.

6. O access_token é usado para chamar a API GraphQL. Quando ele expirar, o refresh_token permite obter novos tokens sem pedir outra autorização ao usuário.

O código de autorização passa pelo navegador, mas as credenciais e os tokens devem permanecer protegidos no servidor.

Quem participa do fluxo

Participante	O que faz
Usuário	Decide se a integração pode acessar sua conta e quais permissões deseja conceder.
Sua integração	Inicia a autorização, recebe o callback e usa os tokens para chamar a API.
Autentique	Autentica o usuário, apresenta a tela de consentimento e emite os códigos e tokens.

Antes de começar

O fluxo apresentado neste guia pressupõe uma aplicação com backend, capaz de:

• guardar o Client Secret e os tokens com segurança;

• criar uma sessão temporária para cada tentativa de autorização;

• receber o callback do Autentique;

• fazer requisições HTTPS para a API.

Não coloque o Client Secret, o access_token ou o refresh_token em JavaScript do navegador, aplicativo móvel, repositório, log ou ferramenta de análise, é assim que os incidentes de segurança mais absurdos ocorrem.

Próximos passos

1. Crie um aplicativo OAuth na página de aplicativos do painel do Autentique.

2. Implemente a autorização do usuário.

3. Obtenha e use os tokens.

4. Consulte Erros e segurança antes de publicar a integração.