Documentação

Autenticação

Autentique requisições da API com tokens Bearer usando sua chave de API.

Todas as requisições de API exigem autenticação usando um token Bearer. Gere uma chave de API no seu painel e inclua-a no cabeçalho Authorization.

Observação: o acesso à API exige um plano Hobby ou superior com faturamento ativo.

Gerando uma Chave de API

  1. Acesse o painel do workspace da sua equipe
  2. Clique em Chaves de API na barra lateral
  3. Clique em Criar chave de API
  4. Copie a chave gerada

Usando Sua Chave de API

Inclua a chave no cabeçalho Authorization:

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"}]}'

Formato do Cabeçalho

Authorization: Bearer YOUR_API_KEY

Testando Sua Chave

Verifique se sua chave de API funciona com o endpoint de autenticação:

curl 'https://your-domain.com/api/v1/auth' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Resposta de Sucesso (200):

{
  "id": "account-uuid",
  "name": "Your Workspace",
  "email": "[email protected]"
}

Chave Inválida (401):

{
  "message": "Missing or invalid Authorization header"
}

Segurança da Chave de API

Boas Práticas

  1. Nunca exponha chaves em código do lado do cliente - as chaves de API devem ser usadas apenas no lado do servidor
  2. Use variáveis de ambiente - não codifique chaves diretamente no seu código
  3. Rotacione chaves periodicamente - exclua chaves antigas e crie novas
  4. Use nomes descritivos - saiba qual chave é usada em cada lugar

Formato da Chave

As chaves são 32 bytes aleatórios codificados em base64url.

Gerenciando Chaves de API

Ver Todas as Chaves

Veja todas as chaves em Workspace > Chaves de API.

Excluir Chaves

Remova chaves que você não precisa mais:

  1. Acesse Chaves de API
  2. Encontre a chave
  3. Clique em Excluir
  4. Confirme a exclusão

Chaves excluídas deixam de funcionar imediatamente.

Respostas de Erro

StatusMensagemCausa
401Missing or invalid Authorization headerCabeçalho não fornecido
401Invalid API keyA chave está incorreta
403API access requires a Hobby plan or above with active billingO plano ou o status de faturamento não permite acesso à API
403Chatbot does not belong to this accountO ID do agente não pertence à conta da chave de API

Configuração de Ambiente

Node.js

const API_KEY = process.env.AGENTKIT_API_KEY;

const response = await fetch('https://your-domain.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chatbotId: 'your-chatbot-id',
    messages: [{ role: 'user', content: 'Hello' }],
  }),
});

Python

import os
import requests

API_KEY = os.environ.get('AGENTKIT_API_KEY')

response = requests.post(
    'https://your-domain.com/api/v1/chat',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json',
    },
    json={
        'chatbotId': 'your-chatbot-id',
        'messages': [{'role': 'user', 'content': 'Hello'}],
    },
)

cURL

export AGENTKIT_API_KEY="your-api-key"

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

Próximos Passos