Autenticación

El esquema Bearer

Envía la API key en el header Authorization en cada 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.

Formato de la key

Toda key v6 de Hablame cumple esta expresión:

^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 lista opcional de redes permitidas: IPs sueltas o bloques CIDR, IPv4 o IPv6. Con lista, la key solo funciona desde esas redes y desde cualquier otra responde 403 AUTH_IP_NOT_ALLOWED; sin lista, funciona desde cualquier red. La lista se fija al crear la key.
• Una fecha de vencimiento opcional. Las keys sin vencimiento no expiran.
• Capacidades concedidas de forma explícita: account (datos financieros), directory (datos personales) y urlshortener.write (crear, editar, borrar y restaurar enlaces cortos). Tener acceso a todos los servicios no las incluye. Como el resto del alcance, se fijan al crear la key y no se le pueden añadir después.

Leer no es escribir: el acortador

En el acortador, el servicio urlshortener deja leer: listar y consultar enlaces, sus estadísticas, el resumen, los dominios y la tarifa. Escribir —crear, editar, borrar y restaurar enlaces— exige además la capacidad urlshortener.write. Así, una integración que solo lee, como un tablero de clics, no necesita una key capaz de redirigir o borrar tus enlaces si alguna vez se filtra.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

{
  "success": false,
  "error": {
    "code": "AUTH_CAPABILITY_NOT_ALLOWED",
    "type": "https://developers.hablame.co/docs/v6/errors/auth-capability-not-allowed",
    "message": "This API key can list and read links, but it cannot create, edit, delete or restore them. Ask an owner or administrator of your organization for an API key that can create and edit links.",
    "details": []
  },
  "meta": {
    "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6",
    "timestamp": "2026-09-30T15:00:00+00:00",
    "responseTimeMs": 0.9
  }
}

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.

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 la key tiene redes permitidas, la petición llega desde una de ellas; si no, AUTH_IP_NOT_ALLOWED. La IP con la que te vimos viene en meta.clientIp.
11. Si el endpoint exige un servicio, la key lo tiene; si no, 403 AUTH_SERVICE_NOT_ALLOWED.
12. Si el endpoint exige una capacidad, la key la tiene; si no, 403 AUTH_CAPABILITY_NOT_ALLOWED. El rechazo llega antes de contar tu límite de uso: no lo gasta.

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

Buenas prácticas de seguridad

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.