Skip to main content
Horneross usa API Keys para autenticar requests a la API. Todas las llamadas a endpoints protegidos deben incluir un token válido.

​
Obtener tu API Key

1

Ir a Configuración

Desde el dashboard, andá a Configuración → API Keys
2

Crear nueva API Key

Click en ”+ Nueva API Key”Completá:
  • Nombre: Para identificarla (ej: “Producción”, “Testing”)
  • Permisos: Qué puede hacer esta key (lectura, escritura, etc.)
3

Copiar el token

IMPORTANTE: Copiá y guardá el token inmediatamente. Por seguridad, solo se muestra una vez.
Nunca compartas tu API key ni la subas a repositorios públicos. Si se filtra, revocala inmediatamente desde el dashboard.

​
Usar la API Key

Incluí tu API key en el header Authorization de cada request: 
curl https://app.horneross.com/api/agents \
  -H "Authorization: Bearer tu_api_key_aqui" \
  -H "Content-Type: application/json"

​
Tipos de API Keys

​
Organization API Key

Acceso a todos los recursos de la organización. Recomendada para backend y automatizaciones. Permisos:
  • ✅ Leer y modificar agentes
  • ✅ Acceder a conversaciones
  • ✅ Gestionar datastores
  • ✅ Ver analíticas

​
Agent-Specific API Key

Acceso limitado a un agente específico. Ideal para integraciones públicas o widgets. Permisos:
  • ✅ Enviar mensajes al agente
  • ✅ Leer respuestas
  • ❌ Modificar configuración del agente
  • ❌ Acceder a otros agentes
Usá Agent-Specific Keys para widgets embebidos en tu sitio web. Son más seguras porque tienen permisos limitados.

​
Permisos granulares

Podés configurar permisos específicos para cada API key:
PermisoDescripción
agents:readListar y ver agentes
agents:writeCrear y modificar agentes
conversations:readLeer conversaciones
conversations:writeCrear conversaciones y mensajes
datastores:readVer datastores y hacer queries
datastores:writeSubir documentos y modificar datastores
analytics:readAcceder a métricas y reportes

​
Ejemplo de key con permisos limitados

{
  "name": "Widget Frontend",
  "permissions": [
    "conversations:write",  // Puede enviar mensajes
    "conversations:read"    // Puede leer respuestas
  ],
  "agentId": "agent_123"    // Solo para este agente
}

​
Renovar y revocar keys

​
Renovar una key

Si creés que tu key se comprometió:
  1. Andá a Configuración → API Keys
  2. Click en “Renovar” en la key comprometida
  3. Se genera un nuevo token
  4. Actualizá tu aplicación con el nuevo token
  5. La key anterior deja de funcionar inmediatamente

​
Revocar una key

Para eliminar una key permanentemente:
  1. Click en “Revocar” en la key
  2. Confirmá la acción
  3. La key deja de funcionar inmediatamente
Revocar una key no se puede deshacer. Asegurate de actualizar todas las aplicaciones que la usen antes de revocarla.

​
Seguridad y mejores prácticas

Nunca hardcodees la API key en tu código:
// ❌ MAL
const apiKey = 'hr_sk_1234567890';

// ✅ BIEN
const apiKey = process.env.HORNEROSS_API_KEY;
Usá keys separadas para desarrollo, staging y producción:
  • HORNEROSS_API_KEY_DEV
  • HORNEROSS_API_KEY_STAGING
  • HORNEROSS_API_KEY_PROD
Si algo sale mal en desarrollo, solo necesitás renovar esa key.
Otorgá solo los permisos mínimos necesarios:
  • Widget público → Solo conversations:write
  • Dashboard interno → agents:read + analytics:read
  • Backend automation → Permisos completos
Aunque no haya compromiso, es buena práctica rotar API keys cada 3-6 meses.
Revisá el uso de cada key en el dashboard. Si ves actividad sospechosa, revocá inmediatamente.

​
Errores de autenticación

​
401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "API key inválida o faltante"
  }
}
Soluciones:
  • Verificá que incluiste el header Authorization
  • Asegurate que el formato sea Bearer tu_api_key
  • Confirmá que la key no fue revocada

​
403 Forbidden

{
  "error": {
    "code": "forbidden",
    "message": "No tenés permisos para acceder a este recurso"
  }
}
Soluciones:
  • Verificá que la API key tenga los permisos necesarios
  • Si es una Agent-Specific Key, asegurate de estar accediendo al agente correcto

​
Rate limiting por API key

Cada API key tiene límites independientes según tu plan: 
{
  "X-RateLimit-Limit": "300",
  "X-RateLimit-Remaining": "275",
  "X-RateLimit-Reset": "1640995200"
}
Headers de respuesta:
  • X-RateLimit-Limit: Límite total por minuto
  • X-RateLimit-Remaining: Requests restantes
  • X-RateLimit-Reset: Timestamp cuando se resetea
Guardá estos headers para implementar retry logic inteligente en tu aplicación.

​
Testing en desarrollo

Para testing local, podés usar una key de desarrollo: 
# .env.local
HORNEROSS_API_KEY=hr_dev_tu_key_de_desarrollo
Las keys de desarrollo tienen límites más bajos pero son gratis. Perfectas para probar integraciones.

​
Próximos pasos

Endpoints de Agentes

Crear y gestionar agentes via API

Enviar mensajes

Integrar chat con tus agentes