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

# Cómo Crear y Gestionar API Keys

> Guía completa para generar, configurar y gestionar API keys de forma segura en gu1 — en el panel gu1 con guía paso a paso, con ejemplos para gestionar api keys.

## Tutorial Interactivo

<Info>
  **Próximamente**: Vídeo interactivo con Clueso estará disponible aquí. Por ahora, sigue la guía paso a paso a continuación.
</Info>

## Visión General

Las **API Keys** de gu1 te permiten integrar la plataforma con tus propios sistemas, automatizar workflows y acceder a datos programáticamente.

### ¿Qué son las API Keys?

Una API Key es una **credencial de autenticación** que identifica tu aplicación al hacer peticiones a la API de gu1. Es como una contraseña, pero diseñada para ser usada por aplicaciones en lugar de usuarios humanos.

<Tip>
  **Seguridad**: Trata tus API keys como contraseñas. Nunca las compartas públicamente, no las incluyas en código versionado (Git) y rótalas periódicamente.
</Tip>

## Tipos de API Keys

<CardGroup cols={2}>
  <Card title="Production Key" icon="building" color="#10b981">
    **Para datos reales**

    * Accede a datos de producción
    * Modifica entidades reales
    * Cobra por uso de integraciones
    * Envía webhooks a endpoints reales
    * Requiere máxima seguridad
  </Card>

  <Card title="Sandbox Key" icon="flask" color="#f59e0b">
    **Para desarrollo y pruebas**

    * Accede a datos de sandbox
    * Ambiente aislado
    * Sin costo adicional
    * Ideal para desarrollo
    * Puede compartirse en equipos de dev
  </Card>
</CardGroup>

## Crear una Nueva API Key

<Steps>
  <Step title="Abrí API Keys">
    Andá a **API Keys** en [https://app.gu1.ai/org-api-keys](https://app.gu1.ai/org-api-keys) (`/org-api-keys`).
  </Step>

  <Step title="Haz Clic en 'Create API Key'">
    En la esquina superior derecha, haz clic en el botón **+ Create API Key** (azul).
  </Step>

  <Step title="Configura la API Key">
    Completa la información:

    **Nombre de la Key**:

    * Usa un nombre descriptivo (ej: "Integration Zapier", "Mobile App", "Data Pipeline")
    * Esto ayuda a identificar el uso más adelante

    **Ambiente**:

    * **Production**: Para aplicaciones en producción
    * **Sandbox**: Para desarrollo y pruebas

    **Permisos** (opcional):
    Por defecto, la key hereda permisos de tu usuario. Puedes restringir:

    * **Read**: Solo lectura de datos
    * **Write**: Crear y modificar entidades
    * **Delete**: Eliminar entidades
    * **Execute**: Ejecutar reglas e integraciones
  </Step>

  <Step title="Copia la API Key">
    <Warning>
      **IMPORTANTE**: La API key completa se mostrará **solo una vez**. Cópiala inmediatamente a un lugar seguro.
    </Warning>

    La key tendrá este formato:

    ```
    gk_production_z1UGrahVx9NA2NG6Pj-6ZuZlFf64CEV73SpUqtt_4fflydka8MmdVAxT0cLqO3d5
    ```

    **Prefijos**:

    * `gk_production_...` - Production key
    * `gk_sandbox_...` - Sandbox key
  </Step>

  <Step title="Almacena de Forma Segura">
    **Opciones recomendadas**:

    * **Gestor de contraseñas**: 1Password, LastPass, Bitwarden
    * **Variables de entorno**: `.env` (¡no commit en Git!)
    * **Secret managers**: AWS Secrets Manager, Google Secret Manager, HashiCorp Vault
    * **CI/CD secrets**: GitHub Secrets, GitLab CI Variables

    **❌ Nunca**:

    * Commitear en el código
    * Compartir por email/Slack
    * Incluir en screenshots
    * Dejar en archivos de log
  </Step>
</Steps>

## Usar tu API Key

### Autenticación HTTP

Todas las peticiones deben incluir la API key en el header `Authorization`:

```bash theme={null}
curl https://api.gu1.ai/entities \
  -H "Authorization: Bearer gk_production_YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Ejemplos de Código

<Tabs>
  <Tab title="JavaScript/Node.js">
    ```javascript theme={null}
    const GUENO_API_KEY = process.env.GUENO_API_KEY;

    // Usando fetch nativo
    const response = await fetch('https://api.gu1.ai/entities', {
      headers: {
        'Authorization': `Bearer ${GUENO_API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
    const data = await response.json();

    // Usando SDK de gu1
    import { GueoClient } from '@gueno/sdk';

    const client = new GueoClient({
      apiKey: GUENO_API_KEY
    });

    const entities = await client.entities.list();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import requests

    GUENO_API_KEY = os.environ['GUENO_API_KEY']

    # Usando requests
    response = requests.get(
        'https://api.gu1.ai/entities',
        headers={
            'Authorization': f'Bearer {GUENO_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    data = response.json()

    # Usando SDK de gu1
    from gueno import GueoClient

    client = GueoClient(api_key=GUENO_API_KEY)
    entities = client.entities.list()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    $apiKey = getenv('GUENO_API_KEY');

    $ch = curl_init('https://api.gu1.ai/entities');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $data = json_decode($response, true);
    curl_close($ch);
    ?>
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'net/http'
    require 'json'

    api_key = ENV['GUENO_API_KEY']

    uri = URI('https://api.gu1.ai/entities')
    request = Net::HTTP::Get.new(uri)
    request['Authorization'] = "Bearer #{api_key}"
    request['Content-Type'] = 'application/json'

    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    data = JSON.parse(response.body)
    ```
  </Tab>
</Tabs>

## Gestionar API Keys Existentes

### Ver Todas las Keys

En la página **API Keys** ([/org-api-keys](https://app.gu1.ai/org-api-keys)), verás una lista de todas las keys activas con información clave como nombre, ambiente, último uso, creación y permisos.

<Info>
  **Nota de Seguridad**: Solo los primeros y últimos 4 caracteres de la key se muestran (ej: `gk_p...3d5`). La key completa no puede recuperarse.
</Info>

### Revocar una API Key

Si una key fue comprometida o ya no es necesaria, puedes revocarla inmediatamente. Esta acción es irreversible y todas las integraciones usando esta key dejarán de funcionar.

### Rotar una API Key

La **rotación** es la práctica de sustituir una key periódicamente por seguridad. Se recomienda rotar API keys de producción cada **90 días**.

<Tip>
  **Proceso de rotación**: Crea una nueva key, actualiza tus sistemas gradualmente, verifica funcionamiento y revoca la key antigua.
</Tip>

## Seguridad y Buenas Prácticas

<CardGroup cols={2}>
  <Card title="Almacenamiento Seguro" icon="lock">
    Usa variables de entorno, secret managers y nunca commites keys en Git
  </Card>

  <Card title="Rotación Regular" icon="rotate">
    Production: cada 90 días, inmediatamente si comprometida
  </Card>

  <Card title="Menor Privilegio" icon="shield-halved">
    Usa permisos mínimos necesarios para cada integración
  </Card>

  <Card title="Monitoreo" icon="chart-line">
    Revisa uso regularmente y configura alertas de anomalías
  </Card>
</CardGroup>

## Rate Limits y Quotas

| Plano            | Requisiciones/min | Requisiciones/día | Burst |
| ---------------- | ----------------- | ----------------- | ----- |
| **Starter**      | 60                | 10.000            | 10    |
| **Professional** | 300               | 100.000           | 50    |
| **Enterprise**   | 1.000             | Ilimitado         | 200   |

La API retorna información de límites en los headers `X-RateLimit-*`.

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/es/api-reference/authentication">
    Documentación completa de la API REST
  </Card>

  <Card title="SDK de gu1" icon="code" href="/es/api-reference/authentication">
    Bibliotecas JavaScript, Python, Ruby, PHP
  </Card>

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

  <Card title="Ejemplos de Código" icon="laptop-code" href="/es/api-reference/integrations/provider-codes">
    Integraciones listas (Zapier, n8n, Make)
  </Card>
</CardGroup>

## ¿Necesitas Ayuda?

* **Documentación**: Navega por nuestras guías completas
* **Email**: [support@gueno.com](mailto:support@gueno.com)
* **Dashboard**: Accede a tu cuenta en [app.gu1.ai](https://app.gu1.ai)

***

**Última actualización**: Enero 2025