Hablame

Autenticación

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

6 min de lectura

El esquema Bearer

Envía la API key en el header Authorization en cada petición:

petición
GET /api/v6/utilities/ping HTTP/1.1
Host:          developers.hablame.co
Authorization: Bearer hk_TU_API_KEY

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

Es intencional. Los tokens en URLs terminan en registros de servidor, en el historial del navegador y en el header Referer que los navegadores envían a dominios de terceros. Un header Bearer no aparece en ninguno de esos lugares.

Formato de la key

Toda key v6 de Hablame cumple esta expresión:

regex
^hk_[a-f0-9]{32}$
  • El prefijo hk_ identifica que es una key v6 de Hablame.
  • 32 caracteres hexadecimales en minúscula (16 bytes de aleatoriedad criptográfica, 128 bits de entropía).
  • Distingue mayúsculas. HK_ o hexadecimal en mayúscula fallan la verificación 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 valor original no se puede recuperar y toca emitir una key nueva.

Ciclo de vida de la key

Creación

Las keys se crean desde el portal de clientes. Cada una lleva:

  • Un vínculo a una organización: toda llamada con esa key opera contra esa organización.
  • Un centro de costo, para la atribución del consumo.
  • Un usuario creador: si lo retiran de la organización, la key deja de funcionar.
  • Una lista opcional de servicios (por ejemplo ["urlshortener", "tts"]) que limita qué endpoints puede llamar. Los endpoints de utilidad bajo /api/v6/utilities/ ignoran esa lista: son universales.
  • Una fecha de vencimiento opcional. Las keys sin vencimiento no expiran.
  • Capacidades concedidas de forma explícita, como account (datos financieros) o directory (datos personales). Tener acceso a todos los servicios no las incluye.

Rotación

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

  1. 01
    Crea la key nueva

    Desde el portal de clientes, con el mismo alcance que la anterior.

  2. 02
    Despliega

    Publica tu aplicación con la key nueva y verifica que responde 200.

  3. 03
    Revoca la anterior

    Cuando confirmes que la nueva funciona, revoca la vieja desde el portal.

La revocación converge en hasta 5 minutos: una key revocada puede seguir autenticando durante esa ventana. Si el token quedó expuesto, avisa a soporte para invalidarla de inmediato.

Vencimiento

Las keys con fecha de vencimiento devuelven 401 AUTH_INVALID_KEY a partir de ese momento. La verificación corre en el servidor en cada petición, así que una key que está por vencer falla exactamente en el segundo en que cruza el límite.

Qué pasa en cada petición

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

  1. El token está presente y prefijado con Bearer; si no, AUTH_REQUIRED.
  2. El token cumple la expresión hk_[a-f0-9]{32}.
  3. El hash del token corresponde a una key conocida.
  4. El token no está vencido.
  5. El usuario creador sigue activo.
  6. Su membresía en la organización sigue activa.
  7. El centro de costo vinculado a la key está activo.
  8. La organización existe y su estado es active.
  9. La organización no tiene bloqueos activos.
  10. Si el endpoint exige un servicio o una capacidad, la key los tiene.

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

Buenas prácticas de seguridad

Sí
No
Guarda las keys en un gestor de secretos (Google Secret Manager, AWS Secrets Manager, HashiCorp Vault, 1Password CLI).
Escribirlas directamente en el código fuente o en imágenes de contenedor.
Inyecta las keys en tiempo de ejecución con variables de entorno leídas al arrancar.
Subir archivos .env con keys reales al control de versiones.
Tener una key por entorno (producción, staging, pruebas) y rotarlas con una cadencia.
Compartir una sola key entre todos los entornos y todo el equipo.
Emitir una key nueva cuando alguien sale del equipo, y revocar la que tenía.
Reusar keys después de una salida.
Enmascarar el token en tus propios registros (hk_***).
Registrar headers Authorization completos, ni siquiera en depuración.

Respuesta a incidentes: token expuesto

Si sospechas que una key se filtró (un commit a un repositorio público, una captura de pantalla, un mensaje en un chat):

  1. Revoca de inmediato desde el portal. La propagación 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 registro de actividad del portal. Busca IPs desconocidas o volúmenes inusuales.
  4. Cita los requestId de las llamadas sospechosas en tu ticket de soporte para que podamos correlacionarlas.