Chaves de API

Gere e gerencie chaves de API para acesso programático.

As chaves de API permitem acesso programático aos seus agentes. Use-as para integrar o Agentkit aos seus aplicativos ou conectar serviços de terceiros.

Criar chaves e usar a API exige um plano Hobby ou superior com faturamento ativo. Os membros do workspace ainda podem visualizar e revogar chaves existentes após perder esse direito de acesso. Faça upgrade do seu plano →

Criando uma chave de API

Vá até o seu workspace
Clique em Chaves de API na barra lateral
Clique em Criar chave de API
Confirme na caixa de diálogo

A nova chave aparece na lista e pode ser revelada ou copiada a qualquer momento.

Visualizando e copiando chaves

Cada chave na lista é mascarada por padrão. Use o ícone de olho para revelar uma chave e o ícone de copiar para copiá-la para a área de transferência.

Usando chaves de API

Inclua a chave nas requisições de API:

curl -X POST 'https://your-domain.com/api/v1/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"chatbotId": "uuid", "messages": [{"role": "user", "content": "Hello"}]}'

Documentação completa da API →

Gerenciando chaves

Ver todas as chaves

Todas as chaves do workspace são listadas na página Chaves de API.

Excluir uma chave

Encontre a chave na lista
Clique no ícone de lixeira
Confirme a exclusão

As chaves excluídas param de funcionar imediatamente.

Revogar chaves após o acesso expirar

Se o seu workspace perder o acesso à API, entre na conta e exclua as chaves desnecessárias na página Chaves de API. Você não precisa renovar o faturamento para revogá-las. Você ainda deve ser membro do workspace. Se você ativou a MFA, conclua a verificação de MFA antes de gerenciar chaves. Até lá, o banco de dados oculta as chaves do workspace e rejeita a exclusão. Isso não restaura o uso da API nem a permissão para criar chaves.

Antes, o Agentkit verificava o direito de acesso pago à API antes de excluir uma chave. As políticas do banco de dados também exigiam esse direito para ler ou excluir chaves. Perder o acesso poderia, portanto, bloquear a remoção de uma credencial existente.

A correção separa a criação da remoção. Ser membro do workspace determina o acesso de leitura e exclusão de chaves existentes, e uma política separada do banco de dados aplica a MFA. Criar e atualizar chaves ainda exige o direito de acesso à API. A ação de exclusão confere tanto o ID da chave quanto o do workspace e só informa sucesso quando o banco de dados retorna uma linha excluída.

Este exemplo simplificado descreve a mudança na verificação:

Before
  Require API entitlement before deleting an existing key.

After
  Delete only a key belonging to the requested workspace.
  Require a returned deleted row before reporting success.
  Keep membership checks and enforce MFA in the database.

Os testes da aplicação simulam o cliente do banco de dados. Eles verificam filtros e tratamento de resultados, não as políticas do banco. Os testes SQL usam contas sintéticas e revertem as alterações. Os resultados esperados incluem:

Verificação	Camada de teste	Resultado esperado
Membro autorizado revoga sem direito de acesso à API	Simulação da aplicação	Sem consulta de direito de acesso; filtros de chave e workspace; sucesso exige uma linha retornada
Membro autorizado revoga sem direito de acesso à API	SQL	Uma chave do próprio workspace excluída
Membro cria uma chave sem direito de acesso	Simulação da aplicação e SQL	Rejeitado
Membro tenta excluir uma chave de outro workspace	SQL	Nenhuma linha excluída
A MFA exigida não é atendida	SQL	Nenhuma linha excluída
A chave solicitada está ausente ou invisível para quem chama	Simulação da aplicação	A ação informa falha

Estas são expectativas de regressão, não resultados de um teste em produção. Aplique o mesmo padrão de teste a credenciais temporárias em fluxos de agentes. Altere o acesso antes da limpeza e confira tanto a limpeza autorizada bem-sucedida quanto a rejeição da limpeza não autorizada.

Boas práticas de segurança

Nunca exponha as chaves

Não faça commit de chaves em repositórios git
Não inclua chaves em código do lado do cliente
Use variáveis de ambiente

Rotacione as chaves periodicamente

Crie novas chaves periodicamente
Atualize seus aplicativos
Exclua chaves antigas

Use chaves separadas

Crie chaves diferentes para:

Produção vs. desenvolvimento
Aplicativos diferentes
Membros de equipe ou serviços diferentes

Escopo da chave

As chaves de API são restritas ao workspace em que foram criadas e têm acesso a:

Todos os agentes do workspace
Endpoints da API de chat
Gerenciamento de webhooks

As chaves não podem:

Gerenciar membros da equipe
Acessar o faturamento
Criar outras chaves de API

Conexão com o Zapier

Ao conectar ao Zapier:

Crie uma chave de API dedicada para o Zapier
Use essa chave na conexão do Zapier
Mantenha a chave separada de outros usos

Configurar o Zapier →

Solução de problemas

Erro "Invalid API key"

Verifique se a chave foi copiada corretamente
Verifique se há espaços antes/depois da chave
Confirme que a chave não foi excluída

Erro "Key not authorized"

Garanta que o agente pertence ao seu workspace
Verifique se o workspace da chave corresponde
Para solicitações à API, confirme que seu workspace está no plano Hobby ou superior com faturamento ativo

A chave não funciona após a criação

Tente atualizar a página
Aguarde 30 segundos para a propagação
Crie uma nova chave se os problemas persistirem