Documentación

Autenticación

Autentica las solicitudes a la API con tokens Bearer usando tu clave de API.

Todas las solicitudes a la API requieren autenticación mediante un token Bearer. Genera una clave de API desde tu panel e inclúyela en el encabezado Authorization.

Nota: El acceso a la API requiere un plan Hobby o superior con facturación activa.

Generar una clave de API

  1. Ve al panel de tu espacio de trabajo de equipo
  2. Haz clic en Claves de API en la barra lateral
  3. Haz clic en Crear clave de API
  4. Copia la clave generada

Usar tu clave de API

Incluye la clave en el encabezado 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 del encabezado

Authorization: Bearer YOUR_API_KEY

Probar tu clave

Verifica que tu clave de API funciona con el endpoint de autenticación:

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

Respuesta de éxito (200):

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

Clave inválida (401):

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

Seguridad de la clave de API

Buenas prácticas

  1. Nunca expongas las claves en código del lado del cliente: las claves de API solo deben usarse en el servidor
  2. Usa variables de entorno: no incluyas las claves directamente en tu código
  3. Rota las claves periódicamente: elimina las claves antiguas y crea nuevas
  4. Usa nombres descriptivos: identifica dónde se usa cada clave

Formato de la clave

Las claves son 32 bytes aleatorios codificados en base64url.

Administrar claves de API

Ver todas las claves

Consulta todas las claves en Espacio de trabajo > Claves de API.

Eliminar claves

Elimina las claves que ya no necesites:

  1. Ve a Claves de API
  2. Busca la clave
  3. Haz clic en Eliminar
  4. Confirma la eliminación

Las claves eliminadas dejan de funcionar de inmediato.

Respuestas de error

EstadoMensajeCausa
401Missing or invalid Authorization headerNo se proporcionó el encabezado
401Invalid API keyLa clave es incorrecta
403API access requires a Hobby plan or above with active billingEl plan o el estado de facturación no permite el acceso a la API
403Chatbot does not belong to this accountEl ID del agente no pertenece a la cuenta de la clave de API

Configuración del entorno

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 pasos