Claves de API de WhatsApp: autenticación, entornos y rotación

La autenticación en la API de WhatsApp de Joinotify es por token Bearer: una clave de API enviada en la cabecera Authorization de cada petición. El secreto completo aparece una sola vez, al crearla; en el servidor solo se guarda el hash. Perder el secreto significa crear una clave nueva y revocar la antigua: no hay recuperación.

curl https://api.joinotify.com/messages \
  -H 'Authorization: Bearer sk_live_xxx'

Anatomía de una clave

Una clave tiene un prefijo visible —algo como sk_live_AbCdEf— y un secreto completo que solo ves una vez. El prefijo es lo que aparece en el panel y en los registros: identifica la clave sin revelarla.

Consecuencia práctica: registra el prefijo, nunca el secreto. Basta para saber qué clave hizo qué.

Dónde guardarla

• Variable de entorno — el mínimo aceptable.
• Un gestor de secretos — lo correcto, con acceso auditado.
• Nunca en el repositorio — ni en un archivo de ejemplo, ni en un comentario, ni en el historial de Git.
• Nunca en el front-end — una clave en JavaScript de navegador es una clave pública.
• Nunca en un blueprint de automatización — los escenarios de Make y los flujos de n8n se exportan y se comparten.

La pregunta que vale la pena hacerse: si este archivo se hiciera público ahora mismo, ¿qué podría enviar un desconocido en nombre de mi empresa?

Una clave por consumidor

Una sola clave para todo es cómodo hasta el día en que necesitas revocar. Sepáralas por quién las usa:

1. Una clave para la aplicación de producción.
2. Una para el entorno de pruebas.
3. Una por integración de terceros: la automatización, el plugin, el script de importación.
4. Una por socio externo, cuando lo haya.

Así, revocar la clave que se filtró en el repositorio de una agencia no tumba la tienda. Con una clave única, cualquier incidente se convierte en una caída general.

Separar entornos

Pruebas y producción necesitan claves distintas y, a ser posible, números distintos. Dos razones concretas:

• Un mensaje de prueba enviado a un cliente real es un incidente de imagen, y ocurre.
• La calidad del número de producción se ve afectada por cualquier envío malo, incluidos los de prueba.

Conviene además protegerlo en el código: si la clave es de producción y el entorno no lo es, rechaza el envío antes de llamar a la API.

Rotación sin caída de servicio

1. Crea la clave nueva y guárdala en el gestor de secretos.
2. Despliega la aplicación leyendo la clave nueva.
3. Confirma, por el prefijo en los registros, que el tráfico ha migrado.
4. Solo entonces revoca la antigua.

El orden importa: revocar antes de desplegar rompe los envíos en el intervalo. Rota periódicamente y siempre que alguien con acceso deje el equipo.

Si se filtra un secreto

1. Revoca la clave de inmediato. Es el acceso, no la alarma.
2. Crea y despliega una nueva.
3. Comprueba qué se envió durante la exposición usando el prefijo comprometido.
4. Si hubo envíos indebidos, evalúa el impacto en la calidad del número.
5. Elimina el secreto de donde se filtró, incluido el historial de Git, donde borrar el archivo no basta.

El paso 5 es el más olvidado: un secreto subido y después borrado sigue siendo accesible en el historial.

Más allá de la clave

• Valida la firma de los webhooks — la clave protege lo que sale; la firma protege lo que entra.
• Restringe quién puede llamar a tu propia capa — no expongas un endpoint interno que envía WhatsApp sin autenticación propia.
• Registra quién disparó qué — la auditoría interna es lo que responde «¿quién mandó ese mensaje?».

La validación de firma está detallada en webhooks de WhatsApp.

Preguntas frecuentes

¿Puedo recuperar una clave perdida?

No. Solo se guarda el hash. Crea una nueva y revoca la antigua.

¿Cuántas claves puedo tener?

Las que tengan sentido. Una por consumidor es el diseño que permite revocar sin tumbarlo todo.

¿La clave de API es lo mismo que el token de Meta?

No. La clave te autentica ante el proveedor; el token de Meta lo usa él, de su lado, y no llega a tus manos.

¿Hay que rotar aunque no haya filtración?

Periódicamente, y obligatoriamente cuando alguien con acceso deja el equipo.