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. Las claves siguen el formato gk_<entorno>_... (ver Formato de clave API). 
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”)
  • Abre Gestionar permisos y elige permisos granulares (pares recurso:acción) alineados con el RBAC del workspace. Concede solo lo que la integración necesite.
  • 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 gk_prod_TU_CLAVE_AQUI"

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

​
Formato de clave API

Las claves son cadenas opacas con prefijo gk_, un segmento de entorno y un sufijo aleatorio (por ejemplo gk_prod_...). El segmento refleja el entorno elegido al crear la clave (producción vs sandbox). Usa claves de producción solo con organizaciones y datos de producción.

​
Permisos

Los permisos son granulares: en el dashboard asignas recursos y acciones permitidos (el mismo modelo recurso:acción que el RBAC del workspace). Cada integración debe recibir el conjunto mínimo necesario para sus endpoints.
Aplica el principio de mínimo privilegio: privilegios explícitos recurso:acción en lugar de acceso amplio.

​
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: 
{
  "valid": true,
  "apiKey": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "API de producción",
    "environment": "prod",
    "organizationId": "550e8400-e29b-41d4-a716-446655440001",
    "scopes": [],
    "rateLimit": 1000,
    "rateLimitRemaining": 999,
    "expiresAt": null,
    "lastUsedAt": "2026-01-10T12:00:00.000Z"
  }
}

​
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

Webhooks

Recibe notificaciones en tiempo real

Flujo KYC completo

Guía de integración KYC de punta a punta