Seguridad

Gestión de Claves API

• Nunca incruste claves en el código — Usa variables de entorno o un gestor de secretos (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault)
• Nunca hagas commit de claves a git — Agrega .env a .gitignore. Usa git-secrets o truffleHog para escanear el historial de tu repositorio
• Usa claves separadas por entorno — Las claves de desarrollo / staging / producción son independientes. Si una clave de desarrollo se filtra, producción no se ve afectada
• Defina el alcance de cada clave — Restringe el acceso a modelos, establece límites de gasto y ponga en lista blanca de IP cada clave al momento de crearla

Rotación de Claves

Rote las claves API cada 90 días. Este es un procedimiento de rotación seguro con validación:

import os
import requests

# Step 1: Create new key via Dashboard or API
NEW_KEY = "sk-new-key-from-dashboard"

# Step 2: Update environment (do this atomically with your deploy)
# In production, use a secrets manager: AWS Secrets Manager, GCP Secret Manager, or Vault
os.environ["TOKSPAN_API_KEY"] = NEW_KEY

# Step 3: Verify new key works
response = requests.post(
    "https://api.tokspan.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {NEW_KEY}"},
    json={"model": "MODEL_NAME", "messages": [{"role": "user", "content": "ping"}]},
    timeout=10,
)
assert response.status_code == 200, f"New key validation failed: {response.status_code}"

# Step 4: Revoke old key in Dashboard → API Keys
# Only do this AFTER confirming new key works in production
print("New key validated. Revoke old key in Dashboard now.")

Proxy de Backend (Requerido para Navegador/Celular)

Nunca llame a TokSpan directamente desde código del lado del cliente. Las claves API expuestas en navegadores o apps móviles pueden ser extraídas por cualquiera. Siempre enrute a través de tu backend:

Browser App → Your Backend API → TokSpan API
                      ↑
              API key lives here
          (never reaches the client)

Tu backend valida la sesión del usuario y luego reenvía la solicitud de IA con la clave API del lado del servidor. El cliente nunca ve la clave.

Lista Blanca de IP

Restringe cada clave API a direcciones IP o rangos CIDR específicos. Incluso si una clave se filtra, es inútil desde redes no autorizadas. Configura en Panel → API Keys → Editar → Lista Blanca de IP. Para claves de producción, ponga en lista blanca solo las IPs de salida de tus servidores backend.

Habilitar MFA

Protege tu cuenta del Panel de TokSpan con autenticación multifactor. Disponible mediante apps autenticadoras TOTP (Google Authenticator, Authy, 1Password). Habilita en Panel → Configuración → Seguridad → MFA.

Auditoría y Monitoreo

Registre el uso de claves para detección de anomalías:

# Monitor API key usage from each response's usage object
import logging

def audit_request(response, key_name):
    usage = response.json().get("usage", {})
    logging.info(f"[{key_name}] model={response.json()['model']} "
                 f"tokens={usage.get('total_tokens', 0)}")

En el Panel, revisa regularmente los Registros de Actividad por clave. Busque: uso inesperado de modelos, picos de tokens, solicitudes desde IPs desconocidas u horarios inusuales.

Si una Clave está Comprometida

1. Revoque inmediatamente — Panel → API Keys → Revocar (toma efecto en <60 segundos)
2. Genera una nueva clave — y actualiza tu aplicación
3. Audita los registros de la clave antigua — Verifica cualquier uso no autorizado antes de eliminarla
4. Investiga cómo se filtró — Revisa el historial de git, registros de CI, mensajes de error, código del lado del cliente
5. Ajuste los alcances — Agrega lista blanca de IP y reduzca el límite de gasto en la clave de reemplazo