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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.