Seguridad

Gestión de Claves API

• Nunca incruste claves en el código — Use variables de entorno o un gestor de secretos (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault)
• Nunca haga commit de claves a git — Agregue .env a .gitignore. Use git-secrets o truffleHog para escanear el historial de su repositorio
• Use 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 — Restrinja el acceso a modelos, establezca 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": "gpt-4o", "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 su backend:

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

Su 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

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

Habilitar MFA

Proteja su cuenta del Panel de TokSpan con autenticación multifactor. Disponible mediante apps autenticadoras TOTP (Google Authenticator, Authy, 1Password). Habilite 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 via response headers
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)} "
                 f"remaining_rpm={response.headers.get('x-ratelimit-remaining-requests', '?')}")

En el Panel, revise 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. Genere una nueva clave — y actualice su aplicación
3. Audite los registros de la clave antigua — Verifique cualquier uso no autorizado antes de eliminarla
4. Investigue cómo se filtró — Revise el historial de git, registros de CI, mensajes de error, código del lado del cliente
5. Ajuste los alcances — Agregue lista blanca de IP y reduzca el límite de gasto en la clave de reemplazo