Autenticación

Hablame v6 usa tokens Bearer (RFC 6750). Un solo header, un solo formato, una sola fuente de verdad. Sin fallbacks por query string, sin flujos OAuth, sin rituales de firma.

El esquema Bearer

Envía la API key en el header Authorization en cada request:

request 
GET /api/v6/utilities/ping HTTP/1.1
Host:          developers.hablame.co
Authorization: Bearer hk_YOUR_API_KEY

El header es la única ubicación aceptada. Tokens enviados en query (?token=…) o en el body se ignoran y la llamada falla con 401 AUTH_REQUIRED.

!

Esto es intencional. Tokens en URLs se filtran a logs de nginx, exports de Cloud Logging, historial del browser y el header Referer que los browsers mandan a dominios de terceros. El header Bearer no aparece en ninguno de esos lugares.

Formato de la key

Toda key v6 de Hablame matchea este regex:

^hk_[a-f0-9]{32}$
  • Prefijo hk_ identifica que es una key v6 de Hablame.
  • 32 caracteres hex en minúscula (16 bytes de aleatoriedad CSPRNG → 128 bits de entropía).
  • Sensible a mayúsculas. HK_ o hex en mayúscula fallan el check estructural y devuelven 401 AUTH_INVALID_KEY.

El token completo solo se muestra al momento de crearlo. El servidor guarda únicamente sha256(token); si pierdes el plaintext no se puede recuperar. Toca emitir una nueva key.

Ciclo de vida de la key

Creación

Las keys se crean desde el dashboard. Cada una carga:

  • Un vínculo a organización: toda llamada organización contra esa organización.
  • Un centro de costos, para atribución de facturación.
  • Un usuario creador: si lo remueven de la organización, la key deja de funcionar.
  • Una lista de servicios opcional (ej. ["sms", "whatsapp"]) que limita qué endpoints de módulo puede llamar. Los endpoints de utilidad (/api/v6/utilities/*) ignoran esta lista y son universales.
  • Una fecha de expiración opcional. Las keys sin expiración nunca vencen.

Rotación

No hay endpoint de rotación por diseño. Para rotar:

  1. Crea una nueva key en el dashboard.
  2. Despliega tu aplicación con la nueva key.
  3. Cuando confirmes que la nueva funciona, revoca la vieja desde el dashboard.

La cache converge en hasta 5 minutos; una key revocada puede seguir autenticando durante esa ventana. Para incidentes de seguridad (exposición del token), avisa a tu account manager: pueden invalidar el cache entry de inmediato.

Expiración

Keys con expires_at devuelven 401 AUTH_INVALID_KEY después de ese timestamp. El check corre server-side en cada request, así que una key que está venciendo falla atómicamente el segundo en que cruza el borde.

Qué pasa en cada request

El pipeline de autenticación corre estos checks en orden. Cualquier falla corta el resto:

  1. Token presente y prefijado con Bearer → si no, AUTH_REQUIRED.
  2. Token matchea el regex hk_[a-f0-9]{32}.
  3. sha256 del token se encuentra en cache o BD.
  4. Token no está vencido.
  5. El usuario creador sigue activo globalmente.
  6. La membresía del usuario en la organización está activa.
  7. El centro de costos vinculado a la key está activo.
  8. La organización existe y su status = 'active'.
  9. La organización no tiene bloqueo (block_general, block_collections, block_security).
  10. Si el endpoint requiere servicio, el array services de la key lo incluye.

Ver el catálogo de errores para el código específico que emite cada paso.

Buenas prácticas de seguridad

SíNo
Guarda las keys en un secret manager (Google Secret Manager, AWS Secrets Manager, HashiCorp Vault, doppler, 1Password CLI). Hardcodearlas en código fuente o imágenes de container.
Inyecta las keys al runtime vía variables de entorno leídas al boot. Subir archivos .env con keys reales al control de versiones.
Tener una key por entorno (prod, staging, sandbox) y rotar en una cadencia. Compartir una sola key entre todos los entornos y todos los ingenieros.
Emitir una nueva key cuando alguien sale del equipo y revocar la que tenía. Reusar keys después de un off-boarding.
Enmascarar el token en tus propios logs (hk_***). Loguear headers Authorization completos, ni siquiera en debug.

Respuesta a incidentes: token expuesto

Si sospechas que una key se filtró (commit a repo público, screenshot, mensaje en un chat):

  1. Revoca de inmediato desde el dashboard. El flush de cache toma hasta 5 minutos; en emergencias, pide a soporte que la invaliden manualmente.
  2. Emite una key de reemplazo y despliega.
  3. Audita el uso reciente en el log de actividad del dashboard. Busca IPs raras o patrones de TPS inusuales.
  4. Cita los request IDs de las llamadas sospechosas en tu ticket de soporte: ops puede correlacionarlos con nuestros logs de infraestructura.