Gestão de chaves de API
A REDA AI pode ser implantada por meio do canal de widget externo, permitindo que o agente de IA alimente um chatbot no seu site ou aplicativo externo. Para proteger esse canal e impedir o uso não autorizado do seu agente, cada agente de widget externo exige uma chave de API exclusiva. Este artigo explica como gerar, gerenciar, revogar e proteger chaves de API.
Entendendo as chaves de API
Uma chave de API é um token longo e criptograficamente seguro que autentica solicitações do seu site ou aplicativo externo para o seu agente da REDA AI. A chave cumpre dois propósitos essenciais:
- Autenticação: comprova que as solicitações vêm do seu aplicativo autorizado, e não de terceiros mal-intencionados.
- Limite de taxa e gestão de cotas: permite que a REDA AI acompanhe o uso por agente de widget externo e aplique limites de taxa para evitar abusos.
Cada agente de widget externo recebe uma chave de API. Se você tiver várias implantações de widget externo, poderá ter várias chaves de API (uma por agente).
Gerando uma chave de API
As chaves de API são geradas diretamente no registro de Definição de Agente para agentes de widget externo.
- Abra o app REDA AI — Clique no Iniciador de aplicativos e selecione REDA AI.
- Acesse as Definições de Agente — No app REDA AI, clique na guia Agentes para ver todos os agentes. Localize e clique no agente configurado para widget externo.
- Role até a seção de chave de API — No registro da Definição de Agente, localize a seção Chave de API Externa (geralmente próxima ao final do formulário). Inicialmente, essa seção exibe "Nenhuma chave de API gerada".
- Clique em "Gerar chave de API" — Uma nova chave de API é gerada e exibida em um campo de texto. A chave completa é mostrada apenas uma vez, no momento da geração.
- Copie a chave imediatamente — Copie a chave completa e cole-a em um local seguro (gerenciador de senhas, documento seguro, variável de ambiente). A chave é mostrada apenas uma vez — depois de sair desta página, ela não pode ser recuperada novamente.
- Salve a Definição de Agente — Clique em Salvar para concluir a geração da chave.
Usando sua chave de API
Incorporando o widget externo
Depois de ter sua chave de API, passe-a para o script de incorporação do widget externo junto com a URL de endpoint da sua organização. A chave vai no atributo data-api-key do código de incorporação. Consulte Configuração do widget externo para ver o trecho de incorporação completo e todos os atributos de configuração disponíveis.
Substitua os valores de espaço reservado pela chave de API que você gerou e copiou da sua Definição de Agente, e pela URL de endpoint da sua organização. O widget usa esses valores para autenticar solicitações ao seu agente da REDA AI.
Controlando origens permitidas
Para impedir que sua chave de API seja usada em sites não autorizados, use o campo Origens Permitidas na Definição de Agente. Esse campo contém uma lista de origens de domínio separadas por vírgula (por exemplo, https://www.example.com, https://app.example.com).
Quando chega uma solicitação com sua chave de API a partir de um domínio que não está na lista de Origens Permitidas, ela é rejeitada. Isso protege contra:
- Vazamento de chave: se sua chave for exposta acidentalmente em código-fonte ou em um repositório público, um invasor só conseguirá usá-la a partir dos domínios que você permitiu explicitamente.
- Ataques entre sites: mesmo que um invasor incorpore o código do seu widget em um site próprio, o serviço da REDA AI rejeitará a solicitação porque o domínio de origem não está na lista de permissões.
Definindo origens permitidas
- Abra a Definição de Agente do seu agente de widget externo.
- Localize o campo Origens Permitidas (ou "Allowed Origins" na interface).
- Informe uma lista de domínios permitidos separados por vírgula, incluindo o protocolo (por exemplo,
https://www.example.com, https://support.example.com). - Salve o registro. As alterações têm efeito imediato.
http://localhost:3000) às suas Origens Permitidas. Remova-as antes de implantar em produção.Limite de taxa e proteção de créditos
A Definição de Agente inclui vários campos para controlar o uso da API e proteger contra custos descontrolados ou abusos:
| Configuração | Finalidade | Exemplo |
|---|---|---|
| Rate Limit Per Hour | Número máximo de solicitações de API por hora. Solicitações que excedam esse limite são limitadas (recebem uma resposta 429 Too Many Requests). | 1000 solicitações/hora |
| Rate Limit Per Session | Número máximo de mensagens por sessão de conversa individual. Impede que um único usuário envie mensagens ilimitadas e consuma créditos em excesso. | 50 mensagens por sessão |
| External Daily Credit Cap | Créditos máximos que podem ser consumidos pelo widget externo em um único dia. Ao atingir o teto, o agente para de responder e retorna um erro de "teto excedido". Útil para controlar custos. | 500 créditos/dia |
Configure esses limites com base no tráfego esperado e nos custos aceitáveis. Por exemplo, se você cobra dos clientes por chamada de API, defina o Limite de Taxa por Hora alto e o Teto de Crédito Diário Externo com base no seu orçamento mensal de créditos.
Revogando e rotacionando chaves de API
Quando revogar uma chave
Revogue uma chave de API se:
- Você suspeita que a chave foi comprometida ou vazada
- Você quer parar de atender solicitações de uma implantação de widget antiga
- Você está rotacionando chaves como parte da sua política de segurança
- Um funcionário que tinha acesso à chave deixou a organização
Como revogar uma chave
- Abra a Definição de Agente do agente de widget externo.
- Na seção Chave de API Externa, clique no botão "Revogar chave de API".
- Uma caixa de diálogo de confirmação pergunta "Tem certeza?" — Clique em OK para confirmar.
- A chave é revogada imediatamente. Todas as solicitações futuras que usarem essa chave serão rejeitadas com um erro de autenticação.
Rotacionando chaves (prática recomendada)
Siga este processo para rotacionar chaves sem tempo de inatividade:
- Gere uma nova chave de API — Clique em "Gerar chave de API" na Definição de Agente. Copie a nova chave.
- Atualize sua implantação do widget — Atualize o código de incorporação no seu site ou aplicativo para usar a nova chave de API. Implante a alteração em produção.
- Aguarde a migração do tráfego — Dê tempo para que os caches sejam limpos e as sessões dos usuários sejam atualizadas (geralmente algumas horas). Monitore o tráfego para confirmar que as solicitações estão usando a nova chave.
- Revogue a chave antiga — Depois de confirmar que todo o tráfego migrou para a nova chave, volte à Definição de Agente e clique em "Revogar chave de API" para desativar a antiga.
Essa abordagem garante que seus usuários não enfrentem interrupções enquanto você rotaciona para uma chave nova e segura.
Armazenamento e segurança da chave de API
Como as chaves são armazenadas
A chave em si nunca é armazenada. O que a REDA AI guarda na definição do agente é um hash SHA-256 unidirecional com um sal aleatório por registro, no formato {nonce}:{hash}. O hash é calculado sobre o ID da sua organização, um segredo do lado do servidor, o sal do próprio registro e a chave, de modo que a mesma chave gerada para dois agentes ainda produz dois valores armazenados diferentes, e nada no registro pode ser revertido em uma chave.
A consequência prática: a chave completa é exibida uma única vez, na geração. Depois ela não pode ser recuperada pela interface, pelo registro, nem por um administrador do Salesforce, não porque esteja oculta, mas porque não está lá. Se você a perder, gera outra.
Protegendo sua chave de API
Trate sua chave de API com a mesma segurança de uma senha:
- Nunca envie para o controle de versão: não inclua a chave no GitHub, GitLab ou em qualquer repositório de código público ou privado.
- Use variáveis de ambiente: armazene a chave em uma variável de ambiente ou em um gerenciador de segredos (AWS Secrets Manager, Azure Key Vault etc.) no seu servidor web. O código de incorporação deve ler a chave do ambiente, sem fixá-la diretamente no código.
- Nunca compartilhe por e-mail: se precisar compartilhar a chave com um colega, use o processo seguro de compartilhamento de credenciais da sua organização (gerenciador de senhas, mensagem criptografada etc.).
- Monitore o acesso: no Salesforce, verifique quem tem acesso ao registro da Definição de Agente. Use as regras de compartilhamento do Salesforce para restringir a visibilidade apenas a administradores autorizados.
- Rotacione regularmente: como prática recomendada de segurança, rotacione as chaves de API periodicamente (por exemplo, trimestral ou anualmente) usando o processo descrito acima.
Solução de problemas com chaves de API
O widget retorna o erro "Unauthorized" ou "Invalid API Key"
Causas possíveis:
- A chave está incorreta: verifique se você copiou a chave completa corretamente. Confira se não faltam caracteres ou há espaços extras.
- A chave está revogada: verifique a Definição de Agente — se nenhuma chave de API estiver exibida, ela pode ter sido revogada. Gere uma nova.
- Origem não permitida: verifique o campo Origens Permitidas. O domínio que está fazendo a solicitação pode não estar na lista de permissões. Atualize as Origens Permitidas, se necessário.
- Chave expirada: se nenhuma chave estiver exibida e o campo estiver vazio, uma chave pode ter expirado ou sido excluída. Gere uma nova.
O widget responde com "Rate limit exceeded"
Causas possíveis:
- Limite por hora excedido: verifique o Limite de Taxa por Hora. Se o seu tráfego excede esse limite, aumente-o ou implemente uma limitação de solicitações no lado do cliente.
- Limite por sessão excedido: verifique o Limite de Taxa por Sessão. Se usuários individuais estiverem atingindo o limite, aumente-o ou oriente-os a iniciar novas conversas.
- Teto diário excedido: verifique o Teto de Crédito Diário Externo. Se esse limite for atingido, nenhuma solicitação será processada até o dia seguinte. Aumente o teto ou recarregue seus créditos.
O widget retorna "Authentication failed"
Causas possíveis:
- A chave de API no código de incorporação não corresponde à chave gerada na Definição de Agente.
- A chave foi revogada após a implantação.
- A Definição de Agente ou o próprio agente foi excluído ou desativado.
Verifique o status da chave e do agente, e gere/reimplante novamente conforme necessário.
Perguntas frequentes
Não. Cada agente de widget externo pode ter apenas uma chave de API ativa por vez. No entanto, você pode ter vários agentes de widget externo, cada um com sua própria chave de API. Se precisar de chaves separadas para implantações diferentes, crie agentes separados para cada implantação.
Revogue imediatamente a chave comprometida clicando em "Revogar chave de API" na Definição de Agente. Em seguida, gere uma nova chave e implante o código de incorporação atualizado no seu site. Se a chave comprometida foi usada em um site não confiável, revise seus registros de uso e o histórico de créditos para verificar atividades suspeitas. Entre em contato com o Suporte da REDA AI se precisar de ajuda para investigar o uso não autorizado.
Não. As chaves de API são exclusivas do canal de widget externo. Slack, Teams, e-mail e outros canais da REDA AI usam seus próprios métodos de autenticação (tokens de workspace, contas de serviço etc.) e não exigem chaves de API.
O widget rejeitará novas solicitações com o código de status HTTP "429 Too Many Requests". O usuário final verá uma mensagem no widget indicando que o agente está temporariamente indisponível. Os limites de taxa são redefinidos no próximo limite de hora ou de sessão, dependendo de qual limite foi excedido. Se você atingir os limites com frequência, aumente as configurações de Limite de Taxa por Hora ou Limite de Taxa por Sessão na Definição de Agente.