Resumo
Aplicativos OAuth permitem que aplicações externas se conectem com segurança à Astra em nome dos usuários. Em vez de compartilhar credenciais, os usuários fazem login na Astra e concedem explicitamente permissão à aplicação. Este guia explica como os Aplicativos OAuth funcionam, como criá-los e gerenciá-los, e quando usá-los em vez de Chaves de API.
Instruções
O que é um Aplicativo OAuth?
Um Aplicativo OAuth é uma aplicação que você registra na Astra para permitir que os usuários autorizem com segurança o acesso ao seu Workspace.
Quando você cria um Aplicativo OAuth, a Astra gera:
Um ID de Cliente, que identifica sua aplicação.
Um Segredo de Cliente, que autentica sua aplicação.
Quando um usuário conecta sua aplicação à Astra, ele é redirecionado para a Astra para fazer login e revisar as permissões que sua aplicação está solicitando. O acesso é concedido apenas após o usuário aprovar a solicitação.
Casos de uso recomendados
Aplicativos OAuth são ideais para:
Produtos SaaS que se conectam à conta Astra de um cliente
Aplicações que exigem consentimento do usuário antes de acessar dados da Astra
Aplicações multi-tenant que atendem a múltiplos clientes ou Workspaces
Integrações que permitem aos usuários conectar sua conta Astra através de um botão Conectar Astra
Quando não usar Aplicativos OAuth
Aplicativos OAuth podem não ser a melhor escolha para:
Scripts internos e automação de back-end
Integrações de sistema a sistema sem interação do usuário
Tarefas agendadas executadas sob uma única conta de organização
Para esses cenários, Chaves de API são tipicamente mais simples de gerenciar.
Como criar um Aplicativo OAuth
Para criar um Aplicativo OAuth:
Faça login na sua conta Astra.
Vá para Conta > Aplicativos OAuth.
Clique em Criar App.
Insira os detalhes necessários:
Nome do App – O nome exibido aos usuários durante a autorização.
URI de Redirecionamento – O URL para onde os usuários são enviados após aprovarem o acesso.
Escopos – As permissões que sua aplicação requer.
Clique em Criar.
Importante: Salve seu Segredo de Cliente imediatamente
Após o app ser criado, a Astra exibe o Segredo de Cliente apenas uma vez.
Copie e armazene o ID do Cliente e o Segredo do Cliente em um local seguro antes de sair da página.
Depois disso, a Astra continuará exibindo o ID do Cliente, mas o Segredo do Cliente completo não poderá ser visualizado novamente.
Entenda os URIs de Redirecionamento
Um URI de Redirecionamento é o destino para onde a Astra envia os usuários após eles aprovarem ou negarem o acesso à sua aplicação.
O URI de Redirecionamento fornecido durante a autorização deve corresponder exatamente a um dos URIs de Redirecionamento registrados para o Aplicativo OAuth. Se os valores não corresponderem, a solicitação de autorização falhará.
Exemplos de URIs de Redirecionamento
Ambiente de produção:
https://seu-app.com/oauth/callback
Ambiente de desenvolvimento local:
http://localhost:8787/callback
Entenda os escopos
Escopos definem as permissões que sua aplicação pode solicitar da Astra.
Os usuários podem revisar essas permissões antes de decidir se autorizam sua aplicação.
Escopos disponíveis
Escopo | Descrição |
Todos | Acesso total a todas as capacidades públicas de API disponíveis |
Chat | Conversar com Agentes |
Agentes: Ler | Visualizar Agentes |
Agentes: Escrever | Criar, atualizar e gerenciar Agentes |
Contatos: Ler | Visualizar contatos |
Contatos: Escrever | Criar, atualizar e gerenciar contatos |
Conversas: Ler | Visualizar histórico de conversas |
Conhecimento: Ler | Visualizar bases de conhecimento |
Conhecimento: Escrever | Criar, atualizar e gerenciar bases de conhecimento |
Webhooks: Gerenciar | Criar e gerenciar webhooks |
Análise: Ler | Acessar dados de análise |
Melhores práticas ao trabalhar com aplicativos OAuth
Solicite apenas as permissões que você precisa
Solicite apenas os escopos necessários para a funcionalidade da sua aplicação.
Solicitar menos permissões ajuda os usuários a entender o que sua aplicação pode acessar e melhora a confiança durante o processo de autorização.
Como o fluxo de autorização funciona (experiência do usuário)
Quando um usuário conecta seu Aplicativo OAuth à Astra:
O usuário clica em Conectar Astra na sua aplicação.
O usuário é redirecionado para a página de autorização da Astra.
A Astra exibe o nome da aplicação e as permissões solicitadas.
O usuário faz login na Astra se ainda não estiver logado.
O usuário clica em Autorizar ou Negar.
Se aprovado, a Astra redireciona o usuário para o URI de Redirecionamento configurado.
Sua aplicação recebe as credenciais de autorização e pode acessar a Astra em nome do usuário.
O que isso significa para os usuários
Os usuários nunca precisam compartilhar suas senhas da Astra com sua aplicação.
Cada usuário concede acesso individualmente.
O acesso se aplica apenas ao Workspace que o usuário autoriza.
Os usuários podem remover o acesso a qualquer momento desconectando a aplicação.
Gerenciar Aplicativos OAuth
A página Aplicativos OAuth exibe todas as aplicações registradas.
Você pode revisar os apps existentes e remover aplicações que não são mais necessárias.
Como excluir um Aplicativo OAuth
Para excluir um Aplicativo OAuth:
Faça login na sua conta Astra.
Abra Conta → Aplicativos OAuth.
Localize a aplicação que deseja remover.
Exclua a aplicação.
Confirme a ação.
O que acontece quando um app é excluído?
Quando um Aplicativo OAuth é excluído:
Novas solicitações de autorização não poderão mais ser iniciadas.
Tokens de acesso existentes são revogados.
Usuários conectados perdem o acesso imediatamente.
Os usuários precisarão se reconectar se um app substituto for criado.
Aplicativos OAuth vs. Chaves de API
Qual opção você deve escolher?
Use a tabela a seguir para determinar qual método de autenticação é melhor para o seu caso de uso.
| Aplicativos OAuth | Chaves de API |
Usuários pretendidos | Clientes e usuários finais | Sistemas internos e serviços de back-end |
Autorização do usuário necessária | Sim | Não |
Tela de consentimento do usuário | Sim | Não |
Suporta múltiplos clientes | Sim | Não |
Tipo de credencial | Tokens de acesso de curta duração que podem ser atualizados | Chaves de API de longa duração |
Caso de uso típico | Integração "Conecte sua conta Astra" | Sincronização de dados automatizada ou fluxo de trabalho interno |
Use Aplicativos OAuth quando os usuários precisarem conectar suas contas Astra e conceder permissão à sua aplicação.
Use Chaves de API quando você estiver criando automações internas, serviços de back-end ou integrações que operam sem interação do usuário.