> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticación

> Aprende cómo autenticarte con la API de gu1 usando claves API — para la API REST de gu1 usando claves API y tokens bearer, con ejemplos para authentication.

## 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](#formato-de-clave-api)).

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Warning>
  ¡Mantén tus claves API seguras! Nunca las confirmes en control de versiones ni las compartas públicamente.
</Warning>

## Obtener tu clave API

<Steps>
  <Step title="Iniciar sesión en el Dashboard">
    Navega a [app.gu1.ai](https://app.gu1.ai) e inicia sesión en tu cuenta
  </Step>

  <Step title="Acceder a la sección de claves API">
    Haz clic en **Configuración** → **Claves API** en la barra lateral
  </Step>

  <Step title="Crear nueva clave">
    Haz clic en el botón **Crear clave API**
  </Step>

  <Step title="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
  </Step>

  <Step title="Copiar y almacenar">
    ¡Copia la clave generada inmediatamente - solo se mostrará una vez!
  </Step>
</Steps>

## Usar tu clave API

Incluye tu clave API en el encabezado `Authorization` de cada solicitud:

```bash theme={null}
curl http://api.gu1.ai/entities \
  -H "Authorization: Bearer gk_prod_TU_CLAVE_AQUI"
```

### Ejemplo con diferentes métodos

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```

  ```javascript JavaScript / Node.js theme={null}
  const response = await fetch('http://api.gu1.ai/entities', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      type: 'company',
      name: 'Acme Corp'
    })
  });
  ```

  ```python Python theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
  }

  data = {
      'type': 'company',
      'name': 'Acme Corp'
  }

  response = requests.post(
      'http://api.gu1.ai/entities',
      headers=headers,
      json=data
  )
  ```
</CodeGroup>

## 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.

<Note>
  Aplica el principio de mínimo privilegio: privilegios explícitos `recurso:acción` en lugar de acceso amplio.
</Note>

## Mejores prácticas

<AccordionGroup>
  <Accordion icon="lock" title="Almacenamiento seguro">
    * 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`)
  </Accordion>

  <Accordion icon="rotate" title="Rotación de claves">
    * 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
  </Accordion>

  <Accordion icon="shield-halved" title="Monitorear uso">
    * Revisa regularmente la actividad de las claves API en el dashboard
    * Configura alertas para patrones de uso inusuales
    * Revoca inmediatamente las claves comprometidas
  </Accordion>

  <Accordion icon="code-branch" title="Separación de entornos">
    * 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
  </Accordion>
</AccordionGroup>

## Respuestas de error

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

### Clave API faltante

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No API key provided"
  }
}
```

**Estado HTTP:** `401 Unauthorized`

### Clave API inválida

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key provided"
  }
}
```

**Estado HTTP:** `401 Unauthorized`

### Clave API expirada

```json theme={null}
{
  "error": {
    "code": "EXPIRED_API_KEY",
    "message": "API key has expired"
  }
}
```

**Estado HTTP:** `401 Unauthorized`

### Permisos insuficientes

```json theme={null}
{
  "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:

| Plan             | Solicitudes por hora | Solicitudes por día |
| ---------------- | -------------------- | ------------------- |
| **Free**         | 100                  | 10,000              |
| **Starter**      | 300                  | 100,000             |
| **Professional** | 1,200                | 500,000             |
| **Enterprise**   | Personalizado        | Personalizado       |

### Encabezados de Límite de Velocidad

Todas las respuestas de la API incluyen información de límite de velocidad en los encabezados:

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 2025-01-15T10:00:00Z
```

| Encabezado              | Descripción                                                        |
| ----------------------- | ------------------------------------------------------------------ |
| `X-RateLimit-Limit`     | Máximo de solicitudes permitidas en la ventana actual              |
| `X-RateLimit-Remaining` | Número de solicitudes restantes en la ventana actual               |
| `X-RateLimit-Reset`     | Marca 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:

```json theme={null}
{
  "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:**

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-01-15T10:00:00Z
Retry-After: 3600
```

<Tip>
  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.
</Tip>

## Probar tu clave API

Usa esta prueba simple para verificar que tu clave API funciona:

```bash theme={null}
curl http://api.gu1.ai/auth/test \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Respuesta exitosa:**

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Crear tu primera entidad" icon="building" href="/es/api-reference/entities/create">
    Comienza a usar la API para crear entidades
  </Card>

  <Card title="Definir esquemas personalizados" icon="table" href="/es/api-reference/data-ingestion/custom-schemas">
    Configura el mapeo de datos para tu caso de uso
  </Card>

  <Card title="Webhooks" icon="webhook" href="/es/webhooks/overview">
    Recibe notificaciones en tiempo real
  </Card>

  <Card title="Flujo KYC completo" icon="book" href="/es/use-cases/kyc/flujo-completo">
    Guía de integración KYC de punta a punta
  </Card>
</CardGroup>