Skip to main content

​
Descripción general

gu1 utiliza claves API para autenticar las solicitudes. Todas las solicitudes API deben incluir tu clave API en el encabezado Authorization usando el esquema Bearer. 
Authorization: Bearer YOUR_API_KEY
¡Mantén tus claves API seguras! Nunca las confirmes en control de versiones ni las compartas públicamente.

​
Obtener tu clave API

1

Iniciar sesión en el Dashboard

Navega a app.gu1.ai e inicia sesión en tu cuenta
2

Acceder a la sección de claves API

Haz clic en Configuración → Claves API en la barra lateral
3

Crear nueva clave

Haz clic en el botón Crear clave API
4

Configurar clave

  • Dale un nombre descriptivo a tu clave (por ejemplo, “API de producción”, “Desarrollo”)
  • Establece permisos (lectura, escritura, admin)
  • Opcionalmente establece una fecha de expiración
5

Copiar y almacenar

¡Copia la clave generada inmediatamente - solo se mostrará una vez!

​
Usar tu clave API

Incluye tu clave API en el encabezado Authorization de cada solicitud: 
curl http://api.gu1.ai/entities \
  -H "Authorization: Bearer sk_live_abc123..."

​
Ejemplo con diferentes métodos

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "company", "name": "Acme Corp"}'

​
Tipos de claves API

gu1 ofrece diferentes tipos de claves API para diferentes entornos:

Claves de producción

Comienzan con sk_live_Utilizadas para entornos de producción. Todas las operaciones son reales y afectan tus datos en vivo.

Claves de prueba

Comienzan con sk_test_Utilizadas para desarrollo y pruebas. Las operaciones no afectan tus datos de producción.

​
Permisos

Las claves API pueden tener diferentes niveles de permisos:
PermisoDescripciónCaso de uso
ReadVer entidades, reglas y datosDashboards de análisis, reportes
WriteCrear y actualizar entidadesIngestión de datos, integraciones API
AdminAcceso completo incluyendo gestión de clavesAutomatización de infraestructura
Sigue el principio de mínimo privilegio - solo otorga los permisos mínimos necesarios para cada integración.

​
Mejores prácticas

  • Almacena las claves API en variables de entorno o sistemas de gestión de secretos
  • Nunca codifiques las claves en tu código fuente
  • Nunca confirmes claves en control de versiones (usa archivos .env y .gitignore)
  • Rota las claves API regularmente (se recomienda cada 90 días)
  • Crea nuevas claves antes de revocar las antiguas para evitar tiempo de inactividad
  • Actualiza todos los sistemas que usan la clave antigua
  • Revisa regularmente la actividad de las claves API en el dashboard
  • Configura alertas para patrones de uso inusuales
  • Revoca inmediatamente las claves comprometidas
  • Usa claves de prueba para desarrollo y staging
  • Usa claves de producción solo en producción
  • Nunca uses claves de producción en máquinas de desarrolladores

​
Respuestas de error

Si la autenticación falla, recibirás una de estas respuestas de error:

​
Clave API faltante

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No API key provided"
  }
}
Estado HTTP: 401 Unauthorized

​
Clave API inválida

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key provided"
  }
}
Estado HTTP: 401 Unauthorized

​
Clave API expirada

{
  "error": {
    "code": "EXPIRED_API_KEY",
    "message": "API key has expired"
  }
}
Estado HTTP: 401 Unauthorized

​
Permisos insuficientes

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have permission to perform this action"
  }
}
Estado HTTP: 403 Forbidden

​
Límite de Velocidad

Las claves API están sujetas a límites de velocidad según tu plan:
PlanSolicitudes por horaSolicitudes por día
Free10010,000
Starter300100,000
Professional1,200500,000
EnterprisePersonalizadoPersonalizado

​
Encabezados de Límite de Velocidad

Todas las respuestas de la API incluyen información de límite de velocidad en los encabezados: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 2025-01-15T10:00:00Z
EncabezadoDescripción
X-RateLimit-LimitMáximo de solicitudes permitidas en la ventana actual
X-RateLimit-RemainingNúmero de solicitudes restantes en la ventana actual
X-RateLimit-ResetMarca de tiempo ISO 8601 cuando el límite de velocidad se reinicia

​
Respuesta de Límite de Velocidad Excedido

Cuando excedas los límites de velocidad, recibirás: 
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Has excedido tu límite de velocidad de la API. Por favor espera antes de hacer más solicitudes.",
  "retryAfter": 3600,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2025-01-15T10:00:00Z"
}
Estado HTTP: 429 Too Many Requests Encabezados de Respuesta: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-01-15T10:00:00Z
Retry-After: 3600
Monitorea los encabezados de límite de velocidad en tus respuestas para implementar limitación de velocidad proactiva en tu aplicación. El encabezado Retry-After indica cuántos segundos debes esperar antes de reintentar.

​
Probar tu clave API

Usa esta prueba simple para verificar que tu clave API funciona: 
curl http://api.gu1.ai/auth/test \
  -H "Authorization: Bearer YOUR_API_KEY"
Respuesta exitosa: 
{
  "authenticated": true,
  "organization_id": "org_abc123",
  "permissions": ["read", "write"],
  "key_type": "live"
}

​
Próximos pasos

Crear tu primera entidad

Comienza a usar la API para crear entidades

Definir esquemas personalizados

Configura el mapeo de datos para tu caso de uso

Configurar webhooks

Recibe notificaciones en tiempo real

Guía de integración

Sigue nuestra guía completa de integración