Autenticación

El esquema Bearer

Envía la clave de API en la cabecera Authorization de cada petición:

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

La cabecera es el único lugar aceptado. Un token enviado en la URL (?token=...) o en el cuerpo se ignora, y la llamada falla con 401 AUTH_REQUIRED.

Formato de la clave

Toda clave v6 de Hablame cumple esta expresión:

^hk_[a-f0-9]{32}$

• El prefijo hk_ identifica que es una clave v6 de Hablame.
• 32 caracteres hexadecimales en minúscula (16 bytes aleatorios, 128 bits).
• Distingue mayúsculas. Con HK_ o con hexadecimal en mayúscula, la API responde 401 AUTH_INVALID_KEY.

El token completo solo se muestra al crearlo. Hablame guarda únicamente una huella (sha256) del token: si pierdes el valor original no se puede recuperar y toca crear una clave nueva.

Ciclo de vida de la clave

Creación

Las claves se crean en Cloud; la guía Tu clave de API explica cómo. Cada una lleva:

• Un vínculo a una organización: toda llamada con esa clave opera contra esa organización.
• Un centro de costo, al que se atribuye el consumo de la clave.
• El usuario que la creó. Queda registrado, pero la clave no depende de él: si ese usuario deja la organización, la clave sigue funcionando hasta que la elimines.
• Los servicios que puede usar (por ejemplo urlshortener). Los endpoints de utilidad bajo /api/v6/utilities/ ignoran esa lista: son universales.
• Una lista opcional de redes permitidas: IP sueltas o rangos CIDR, IPv4 o IPv6. Con lista, la clave 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 clave.
• Una fecha de vencimiento opcional. Las claves sin vencimiento no caducan.
• Capacidades de la cuenta, concedidas de forma explícita: account (datos financieros) y directory (datos personales). Son las únicas: dentro de un servicio no hay permisos parciales. Tener acceso a todos los servicios no las incluye. Como el resto del alcance, se fijan al crear la clave y no se pueden añadir después.

Cada servicio se da completo

El permiso de una clave sobre un servicio es total o no existe. Con urlshortener, la clave lista y consulta enlaces, y también los crea (cada alta se cobra), los edita, los elimina y los restaura. Con storage, ve el resumen, el consumo, los archivos y sus descargas. Si una integración no debe crear ni borrar enlaces, como un tablero de visitas, no le des el servicio del acortador.

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

{
  "success": false,
  "error": {
    "code": "AUTH_SERVICE_NOT_ALLOWED",
    "type": "https://developers.hablame.co/docs/v6/errors/auth-service-not-allowed",
    "message": "This API key is not authorized to use the requested service.",
    "details": []
  },
  "meta": {
    "requestId": "8f0c0e2a4b1d4c8f",
    "clientIp": "203.0.113.45",
    "timestamp": "2026-09-30T15:00:00+00:00",
    "responseTimeMs": 0.9
  }
}

Rotación

No hay un endpoint de rotación, a propósito. Para rotar:

1. 01
   Crea la clave nueva

   En Cloud, con los mismos permisos que la anterior.

2. 02
   Despliega

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

3. 03
   Elimina la anterior

   Cuando confirmes que la nueva funciona, elimina la vieja en Cloud.

Vencimiento

Las claves con fecha de vencimiento responden 401 AUTH_INVALID_KEY a partir de ese momento. La verificación se hace en el servidor en cada petición y una clave guardada en memoria no sobrevive a su fecha, así que una clave por vencer falla exactamente al cruzar el límite.

Qué pasa en cada petición

La API hace estas verificaciones en orden. Cualquier falla corta el resto:

1. El token está presente y precedido de Bearer; si no, 401 AUTH_REQUIRED.
2. La huella del token corresponde a una clave que existe, no fue eliminada y no ha vencido; si no, 401 AUTH_INVALID_KEY.
3. La organización de la clave está activa; si no, 403 ACCOUNT_NOT_ACTIVE.
4. Si la clave tiene redes permitidas, la petición llega desde una de ellas; si no, 403 AUTH_IP_NOT_ALLOWED. La IP con la que te vimos viene en meta.clientIp.
5. Si el endpoint exige un servicio, la clave lo tiene (y la organización no lo apagó); si no, 403 AUTH_SERVICE_NOT_ALLOWED.
6. Si el endpoint exige una capacidad de la cuenta (account o directory), la clave la tiene; si no, 403 AUTH_CAPABILITY_NOT_ALLOWED. Este rechazo llega antes de contar tu límite de uso: no lo gasta.

Si el servicio que verifica las claves no responde, la API no te deja pasar: responde 503 SERVICE_UNAVAILABLE. Reintenta en unos segundos. El catálogo de errores tiene el detalle de cada código.

Buenas prácticas de seguridad

Si el token se expone

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

1. Elimínala de inmediato en Cloud. Deja de servir en un máximo de 30 segundos; si necesitas que sea al instante, avisa a soporte.
2. Crea una clave de reemplazo y despliega.
3. En Cloud mira cuándo se usó por última vez la clave y compáralo con tus registros. Busca IP desconocidas (la IP con la que te vimos viene en meta.clientIp de cada respuesta) o volúmenes inusuales.
4. Cita los requestId de las llamadas sospechosas en tu mensaje a soporte para que podamos correlacionarlas.

Para comprobar tu nueva clave basta una llamada a https://developers.hablame.co/api/v6/utilities/ping.