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

# API Keys

> Crea, lista y elimina API keys para integrarte con Trébol. Desde el Aplicativo Web o vía API.

Las API keys autentican tus llamadas al API de Trébol. Cada request incluye tu API key en el header `x-api-key`.

Puedes crear y gestionar tus API keys de dos formas:

* **Desde el Aplicativo Web** — flujo manual, ideal para configuración inicial o crear keys puntuales.
* **Vía API** — para integraciones que necesitan crear, listar o eliminar keys programáticamente (por ejemplo, rotación automática).

<Warning>
  **La API key solo se muestra una vez** al crearla — tanto en el Aplicativo Web como en la respuesta del endpoint POST. Guárdala en un lugar seguro inmediatamente; no podrás recuperarla después.
</Warning>

## Quién puede crear API Keys

* **Usuarios administradores**: tienen los permisos necesarios por defecto.
* **Usuarios con permisos específicos de API Keys**: asignados por el administrador de la cuenta.

***

## Desde el Aplicativo Web

<Steps>
  <Step title="Ingresar al Aplicativo Web">
    Accede a [app.gotrebol.com](https://app.gotrebol.com) con tu cuenta.
  </Step>

  <Step title="Navegar a Ajustes">
    En la parte superior derecha de la pantalla, haz clic en el icono de ajustes para abrir el menú de configuración.
  </Step>

  <Step title="Abrir Claves secretas">
    Dentro del menú de ajustes, selecciona **Claves secretas** para gestionar las API keys.
  </Step>

  <Step title="Crear una nueva API Key">
    Haz clic en **Crear API Key** e ingresa un nombre fácil de identificar relacionado con su propósito (por ejemplo `produccion-2024` o `integracion-crm`).
  </Step>

  <Step title="Guardar la API Key en un lugar seguro">
    La API Key solo se mostrará una vez. Cópiala y guárdala en un gestor de secretos antes de cerrar la ventana.
  </Step>
</Steps>

***

## Vía API

Usa estos endpoints para gestionar tus API keys programáticamente.

### Listar API Keys

Obtiene la lista de todas las API keys asociadas a tu cuenta.

**Endpoint:** `GET /api-keys`

**Headers requeridos:**

```
x-api-key: tu_api_key_aqui
```

**Respuesta exitosa (200):**

```json theme={"dark"}
{
  "api_keys": [
    {
      "id": "ak_1234567890abcdef",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "ak_0987654321fedcba",
      "created_at": "2024-01-10T14:20:00Z"
    }
  ]
}
```

### Crear Nueva API Key

Crea una nueva API key para tu cuenta.

**Endpoint:** `POST /api-keys`

**Headers requeridos:**

```
x-api-key: tu_api_key_aqui
Content-Type: application/json
```

**Body:**

```json theme={"dark"}
{
  "id": "mi-api-key-1"
}
```

**Respuesta exitosa (201):**

```json theme={"dark"}
{
  "id": "ak_1234567890abcdef",
  "api_key": "treb_sk_live_1234567890abcdef1234567890abcdef1234567890abcdef",
  "created_at": "2024-01-15T10:30:00Z"
}
```

<Warning>
  La API key solo se muestra una vez en la respuesta. Guárdala en un lugar seguro inmediatamente.
</Warning>

### Eliminar API Key

Elimina una API key específica de tu cuenta.

**Endpoint:** `DELETE /api-keys/{apiKeyId}`

**Headers requeridos:**

```
x-api-key: tu_api_key_aqui
```

**Respuesta exitosa (200):**

```json theme={"dark"}
{
  "message": "API key eliminada exitosamente"
}
```

### Ejemplos de código

<CodeGroup>
  ```bash cURL theme={"dark"}
  # Listar API keys
  curl -X GET "https://api.gotrebol.com/api-keys" \
    -H "x-api-key: tu_api_key_aqui"

  # Crear nueva API key
  curl -X POST "https://api.gotrebol.com/api-keys" \
    -H "x-api-key: tu_api_key_aqui" \
    -H "Content-Type: application/json" \
    -d '{ "id": "mi-api-key-1" }'

  # Eliminar API key
  curl -X DELETE "https://api.gotrebol.com/api-keys/ak_1234567890abcdef" \
    -H "x-api-key: tu_api_key_aqui"
  ```

  ```javascript JavaScript theme={"dark"}
  const API_BASE_URL = 'https://api.gotrebol.com';
  const API_KEY = 'tu_api_key_aqui';

  // Listar API keys
  async function listApiKeys() {
    const response = await fetch(`${API_BASE_URL}/api-keys`, {
      method: 'GET',
      headers: { 'x-api-key': API_KEY }
    });
    const data = await response.json();
    return data.api_keys;
  }

  // Crear nueva API key
  async function createApiKey(id) {
    const response = await fetch(`${API_BASE_URL}/api-keys`, {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ id })
    });
    return response.json();
  }

  // Eliminar API key
  async function deleteApiKey(apiKeyId) {
    const response = await fetch(`${API_BASE_URL}/api-keys/${apiKeyId}`, {
      method: 'DELETE',
      headers: { 'x-api-key': API_KEY }
    });
    return response.json();
  }
  ```

  ```python Python theme={"dark"}
  import requests

  API_BASE_URL = 'https://api.gotrebol.com'
  API_KEY = 'tu_api_key_aqui'

  headers = {'x-api-key': API_KEY}

  # Listar API keys
  def list_api_keys():
      response = requests.get(f'{API_BASE_URL}/api-keys', headers=headers)
      return response.json()

  # Crear nueva API key
  def create_api_key(key_id):
      data = {'id': key_id}
      response = requests.post(
          f'{API_BASE_URL}/api-keys',
          headers={**headers, 'Content-Type': 'application/json'},
          json=data
      )
      return response.json()

  # Eliminar API key
  def delete_api_key(api_key_id):
      response = requests.delete(
          f'{API_BASE_URL}/api-keys/{api_key_id}',
          headers=headers
      )
      return response.json()
  ```
</CodeGroup>

### Códigos de Error

| Código | Descripción                              |
| ------ | ---------------------------------------- |
| 400    | Datos de entrada inválidos               |
| 401    | API key inválida o no autorizada         |
| 404    | API key no encontrada (solo para DELETE) |
| 409    | ID de API key ya existe (solo para POST) |
| 500    | Error interno del servidor               |

***

## Mejores Prácticas

### Seguridad

* **Guarda las API keys de forma segura**: usa un gestor de secretos (AWS Secrets Manager, HashiCorp Vault, etc.). Recuerda que solo se muestran una vez.
* **Nombres descriptivos**: usa IDs que ayuden a identificar el propósito de cada key.
* **Rota las API keys regularmente**: elimina las que ya no uses y crea nuevas periódicamente.
* **No compartas las API keys**: nunca las incluyas en código público, repositorios ni logs.
* **Usa variables de entorno** para inyectar la key en tu aplicación, no la hardcodees.

### Ejemplos de IDs descriptivos

```
api-key-produccion-2024
api-key-desarrollo-test
api-key-webhook-notificaciones
api-key-integracion-crm
```

### Gestión de entornos

Usa diferentes API keys para **desarrollo**, **staging** y **producción**. Elimina las de desarrollo cuando ya no las necesites.

### Rotación de API Keys

1. Crea una nueva API key.
2. Actualiza tu aplicación con la nueva key.
3. Verifica que todo funcione correctamente.
4. Elimina la API key antigua.

### Respuesta ante compromiso

Si sospechas que una API key ha sido comprometida:

1. Crea inmediatamente una nueva API key.
2. Actualiza todas las aplicaciones que usan la key comprometida.
3. Elimina la API key comprometida.
4. Monitorea el uso para detectar actividad sospechosa.