Skip to main content

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.

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

​
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

1

Ingresar al Aplicativo Web

Accede a app.gotrebol.com con tu cuenta.
2

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

Abrir Claves secretas

Dentro del menú de ajustes, selecciona Claves secretas para gestionar las API keys.
4

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).
5

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.

​
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): 
{
  "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: 
{
  "id": "mi-api-key-1"
}
Respuesta exitosa (201): 
{
  "id": "ak_1234567890abcdef",
  "api_key": "treb_sk_live_1234567890abcdef1234567890abcdef1234567890abcdef",
  "created_at": "2024-01-15T10:30:00Z"
}
La API key solo se muestra una vez en la respuesta. Guárdala en un lugar seguro inmediatamente.

​
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): 
{
  "message": "API key eliminada exitosamente"
}

​
Ejemplos de código

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

​
Códigos de Error

CódigoDescripción
400Datos de entrada inválidos
401API key inválida o no autorizada
404API key no encontrada (solo para DELETE)
409ID de API key ya existe (solo para POST)
500Error 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.