For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

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

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:

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.

Atualizado