Obtendo e usando os tokens

Troque o código de autorização por tokens, chame a API GraphQL e renove o acesso.

Depois de validar o callback, seu backend pode trocar o código de autorização por tokens.

Faça essa requisição somente no servidor. O Client Secret, o code_verifier e os tokens nunca devem ser enviados ao navegador.

Troque o código por tokens

Envie uma requisição POST para:

https://api.autentique.com.br/oauth/token

Use o formato application/x-www-form-urlencoded:

curl --request POST 'https://api.autentique.com.br/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode "client_id=${AUTENTIQUE_CLIENT_ID}" \
  --data-urlencode "client_secret=${AUTENTIQUE_CLIENT_SECRET}" \
  --data-urlencode "redirect_uri=${AUTENTIQUE_REDIRECT_URI}" \
  --data-urlencode "code=${AUTHORIZATION_CODE}" \
  --data-urlencode "code_verifier=${CODE_VERIFIER}"

Use exatamente:

• o código recebido no callback;

• o code_verifier criado no início da mesma autorização;

• a mesma URL de redirecionamento enviada ao endpoint de autorização;

• as credenciais do aplicativo que iniciou o fluxo.

A resposta inclui:

• access_token;

• refresh_token;

• token_type;

• informações de expiração.

O access_token vale 15 dias. O refresh_token vale 365 dias.

Guarde os tokens de forma protegida no servidor e associe-os ao usuário ou à organização que autorizou a integração.

Chame a API GraphQL

Envie o access_token como Bearer para:

https://api.autentique.com.br/v2/graphql

Este exemplo busca os dados do usuário autorizado e precisa da permissão user:read:

curl --request POST 'https://api.autentique.com.br/v2/graphql' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"query":"query { me { id name email } }"}'

O usuário pode conceder menos permissões do que sua integração solicitou. Antes de depender de uma operação, confirme que o acesso necessário foi concedido e trate respostas sem autorização.

Renove os tokens

Quando o access_token expirar, use o refresh_token para obter um novo par de tokens:

curl --request POST 'https://api.autentique.com.br/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "client_id=${AUTENTIQUE_CLIENT_ID}" \
  --data-urlencode "client_secret=${AUTENTIQUE_CLIENT_SECRET}" \
  --data-urlencode "refresh_token=${REFRESH_TOKEN}"

A renovação retorna novos valores para access_token e refresh_token.

Substitua os dois valores armazenados conjuntamente. Depois que o novo refresh_token for emitido, não reutilize o anterior.

Evite que duas requisições tentem renovar os mesmos tokens ao mesmo tempo. Uma estratégia comum é usar um bloqueio por conexão durante a renovação e liberar as outras requisições somente depois que o novo par estiver salvo.

Se a renovação falhar porque o refresh_token expirou, foi revogado ou já foi substituído, inicie uma nova autorização com o usuário.

Proteja os tokens

• Armazene os tokens criptografados ou em um serviço apropriado para segredos.

• Nunca coloque tokens em URLs.

• Não registre tokens completos em logs ou ferramentas de análise.

• Limite o acesso aos tokens aos serviços que realmente chamam a API.

• Apague os tokens quando a integração for desconectada.

• Trate os tokens como credenciais, mesmo que tenham data de expiração.

Coleção Postman

Para um exemplo prático, importe a coleção do OAuth 2.0 no Postman:

Baixar Autentique OAuth 2.0.postman_collection.json

Próximas operações

Com um access_token válido, você pode continuar para:

• user:read: Buscar Usuário Atual;

• documents:read: Resgatar um documento;

• documents:read: Listar documentos;

• documents:create: Criar um Documento;

• documents:update: Editar um Documento.

Para respostas inesperadas, consulte Erros e segurança.