¿Cómo funcionan las claves API?

Las claves API son tus credenciales de autenticación para acceder a la API de Cathopic. Entender cómo funcionan es esencial para una integración API segura y efectiva.

¿Qué es una clave API?

Una clave API es un token secreto único que identifica tu aplicación y la autoriza a acceder a la API de Cathopic:

• Una cadena alfanumérica larga (ej., sk_live_abc123xyz789...)

• Actúa como autenticación y autorización

• Vinculada a tu cuenta de Cathopic y facturación

• Puede estar activa o inactiva

Ciclo de vida de la clave

Creación:

1. Genera claves en Ajustes → API

2. Dale a cada clave un nombre descriptivo ("Website Producción", "Staging", "App Móvil")

3. Copia la clave completa inmediatamente - solo se muestra una vez

4. Almacena de forma segura (variables de entorno, gestor de secretos, gestor de contraseñas)

Uso:

• Incluye en el header HTTP x-api-key con cada petición

• Las claves se validan del lado del servidor en cada petición

• Todo el uso de la API se rastrea y factura a tu cuenta

Desactivación:

• Las claves pueden desactivarse temporalmente sin eliminarlas

• Útil para solucionar problemas o pausar una integración específica

• Pueden reactivarse en cualquier momento

Eliminación:

• Elimina permanentemente la clave

• No se puede deshacer o recuperar

• Todas las peticiones con esa clave fallarán inmediatamente

Pautas de gestión de claves

Seguridad:

• Nunca las commits a control de versiones: Usa archivos .env y añádelos a .gitignore

• Nunca las expongas en código del lado del cliente: Las claves API solo deben usarse del lado del servidor

• Usa variables de entorno: Almacena las claves en process.env.CATHOPIC_API_KEY o equivalente

• Rota regularmente: Cambia las claves periódicamente (trimestral o después de cambios de equipo)

• Usa claves separadas por entorno: Diferentes claves para dev, staging y producción

Organización:

• Nombres descriptivos: Nombra las claves por propósito: "Website Producción", "App iOS", "Sistema Email"

• Documenta la propiedad: Rastrea qué miembro del equipo creó cada clave

• Auditorías regulares: Revisa las claves activas mensualmente y elimina las no usadas

Múltiples claves API

Puedes crear múltiples claves API para diferentes propósitos:

• Por entorno: Claves separadas para desarrollo, staging, producción

• Por aplicación: Diferentes claves para sitio web, app móvil, herramientas internas

• Por miembro del equipo: Claves individuales para desarrolladores (más fácil de rastrear y revocar)

Todas las claves bajo tu cuenta comparten la misma facturación. El uso de todas las claves se combina en tu factura mensual.

Monitorear el uso de claves

Rastrea la actividad de cada clave:

1. Ve a Ajustes → API

2. Ver lista de todas las claves con fechas de último uso

3. Haz clic en una clave para ver estadísticas de uso detalladas

4. Monitorea por actividad inesperada

Qué hacer si una clave está comprometida

Si crees que una clave API ha sido expuesta:

1. Elimina o desactiva inmediatamente la clave en Ajustes → API

2. Genera una nueva clave de reemplazo

3. Actualiza tu aplicación con la nueva clave

4. Revisa los logs de uso para cualquier actividad sospechosa

5. Contacta con soporte si ves uso no autorizado

Ejemplo: Almacenar claves de forma segura

Node.js con variables de entorno:

// archivo .env (¡añadir a .gitignore!)
CATHOPIC_API_KEY=sk_live_abc123xyz789...
// Tu código
require('dotenv').config();
const apiKey = process.env.CATHOPIC_API_KEY;
fetch('https://api.cathopic.com/resources', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'Jesús' })
});

Python con variables de entorno:

import os
import requests
api_key = os.environ.get('CATHOPIC_API_KEY')
response = requests.post(
    'https://api.cathopic.com/resources',
    headers={'x-api-key': api_key},
    json={'query': 'Jesús'}
)