Compartir enlaces de forma segura: guía para desarrolladores

Si eres ingeniero, compartir secretos suele aparecer en tres momentos: la incorporación, la entrega a proveedores y la respuesta a incidentes. Aquí tienes la visión de un desarrollador sobre cuándo usar un enlace de un solo uso, cuándo no hace falta y cómo generarlo desde un script sin que el secreto se filtre al historial de la shell por el camino. Si quieres probar el mecanismo antes, el generador gratuito de enlaces secretos de un solo uso no necesita cuenta.

¿Cuándo debe usar un desarrollador un enlace de un solo uso?

Cuando hay una persona en al menos un extremo de la entrega y el valor no debe quedarse en ningún sitio después. Los casos habituales:

• La incorporación de un ingeniero nuevo con su primer juego de credenciales.
• Compartir una contraseña de administrador temporal durante un incidente.
• Entregar un token a un proveedor o colaborador externo que no debe estar en tu bóveda.
• Rotar una credencial cuyo valor antiguo debe dejar de servir enseguida.
• Enviar a un cliente la clave de API que le has generado.

Cuándo no usar un enlace de un solo uso

• Secretos entre máquinas. Las variables de entorno de la CI (por ejemplo, los secretos de GitHub Actions), los Secrets de Kubernetes y las credenciales dinámicas de Vault son la pieza adecuada ahí. Un enlace sirve para la entrega de una persona hacia esos sistemas.
• Credenciales de equipo de larga duración. Su sitio es un gestor de contraseñas.
• Configuración pública. No disfraces de secreto una configuración que no lo es. Usa un enlace normal.

La línea divisoria: si los dos extremos de la transferencia son máquinas, usa el almacén de secretos de tu plataforma. Si al menos uno es una persona, un enlace de un solo uso suele ser la pieza más limpia.

Generarlo desde un script

LinkPilot tiene una API REST disponible en todos los planes, incluido el Free (los límites de uso cambian según el plan). Generar un secreto desde un script tiene este aspecto:

LP_KEY=lp_live_...

URL=$(curl -sS https://api.uselinkpilot.com/v1/secrets \
  -H "Authorization: Bearer $LP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "'"$NEW_DB_PASSWORD"'",
    "expires_in": 3600,
    "burn_after_read": true,
    "passphrase": "'"$ONBOARDING_PASSPHRASE"'"
  }' | jq -r '.url')

echo "Secret link: $URL"

Pasa esa URL al canal de entrega que ya uses: un mensaje directo de Slack, el correo o el webhook de tu herramienta de incorporación.

Mantener el contenido fuera de la lista de procesos

El fragmento anterior tiene un defecto clásico: al interpolar el contenido en -d, este acaba en la línea de comandos de curl, donde cualquier usuario local puede leerlo con ps mientras dura la petición. Construye el JSON con jq y pásalo por la entrada estándar con la opción -d @- de curl:

set -euo pipefail

jq -n --arg payload "$NEW_DB_PASSWORD" \
      --arg pass "$ONBOARDING_PASSPHRASE" \
      '{payload: $payload, expires_in: 3600,
        burn_after_read: true, passphrase: $pass}' |
curl -sS https://api.uselinkpilot.com/v1/secrets \
  -H "Authorization: Bearer $LP_KEY" \
  -H "Content-Type: application/json" \
  -d @- | jq -r '.url'

Tres hábitos que conviene convertir en reflejo:

• Los valores llegan por variables de entorno o por la CLI de un gestor de secretos, nunca tecleados en una shell interactiva donde acaban en el historial.
• El script imprime el enlace, nunca el contenido.
• set -euo pipefail, para que una llamada fallida a la API no pase en silencio una URL vacía al paso siguiente.

Plantilla de incorporación

Un esquema que funciona bien con los ingenieros nuevos el primer día:

1. El script de incorporación crea las cuentas y obtiene credenciales de un solo uso.
2. El script crea un enlace secreto por credencial, con expiración de 4 horas y una frase de contraseña común.
3. El script envía un correo con todos los enlaces y un mensaje directo de Slack con la frase de contraseña.
4. El ingeniero abre cada enlace y copia la credencial en su gestor de contraseñas.
5. Lo que siga sin leer al final del día se revoca y se vuelve a emitir cuando le venga bien.

Por qué estos parámetros: la expiración de 4 horas cubre una primera mañana normal sin dejar credenciales activas durante la noche; la frase de contraseña viaja por un segundo canal, así que un correo reenviado o mal entregado no supone ningún riesgo; y como cada enlace se destruye tras la lectura, el buzón del ingeniero termina el día solo con URL que ya no funcionan.

Díselo de forma explícita a la persona nueva: «cada enlace funciona una vez; guarda el valor en tu gestor de contraseñas antes de cerrar la pestaña». El error más común en la incorporación es que el destinatario lea el secreto, cierre la pestaña y crea que puede volver más tarde.

Un procedimiento de rotación

Para rotar una contraseña compartida de base de datos cuando quien la recibe es un colaborador externo o un compañero:

1. Genera la contraseña nueva y aplícala en el sistema de origen (la base de datos, la consola de la nube o donde esté la versión de referencia).
2. Actualiza antes tus propios consumidores (bóveda de la CI, secret de K8s, configuración de la aplicación) para que nada se rompa mientras se hace la entrega a la persona.
3. Crea un enlace de un solo uso para el valor nuevo: se destruye tras la lectura, expira en 1 hora y lleva frase de contraseña.
4. Entrega el enlace y la frase de contraseña por canales distintos.
5. Comprueba el evento de vista en el historial de auditoría. ¿No hay vista antes de la expiración? Revoca y vuelve a emitir; no reenvíes nunca el mismo enlace.
6. Confirma que la credencial antigua está desactivada en el origen.

Cada rotación lleva su propio enlace. Los enlaces son independientes por diseño: para la entrega es una ventaja, para el control no aporta nada, así que el calendario de rotación vive en tu gestor o en tu procedimiento, no en la herramienta de enlaces.

Respuesta a incidentes

Durante un incidente a menudo hay que rotar una credencial y repartir la nueva entre unas pocas personas, rápido. No la pegues en el canal del incidente: ese canal se guarda para el análisis posterior, y el secreto acabará en la exportación, en el documento de retrospectiva y en todos los sistemas de retención que vengan detrás.

• Rota la credencial en el sistema de origen.
• Genera un enlace secreto con expiración de 30 minutos.
• Deja el enlace en el canal; envía la frase de contraseña por mensaje directo.
• Después del incidente, confirma que el enlace se ha destruido o revocado.

Así, el análisis posterior contiene una URL que ya no funciona en lugar de una contraseña de administrador válida, y el historial de auditoría le da a quien revise la cronología un registro exacto, sin trabajo adicional: «credencial reemitida a las 14:32, leída a las 14:33».

Una nota sobre las vistas previas: los clientes de chat descargan las URL pegadas para mostrar una vista previa. Un enlace secreto bien diseñado lo resiste porque la vista previa hace un GET y para mostrar el secreto hace falta un POST explícito. El mecanismo completo está en escáneres de enlaces y secretos de un solo uso. Si estás evaluando una herramienta, pruébalo antes de un incidente, no durante uno.

¿Qué te dice el historial de auditoría?

Si un secreto se ha leído, cuándo y, de forma aproximada, desde dónde, y si alguien ha probado una frase de contraseña incorrecta. Cada secreto de LinkPilot lleva una cronología de eventos: created, viewed, failed_passphrase, burned, expired, revoked. Las vistas se registran con la marca de tiempo, una geolocalización aproximada cuando está disponible, el user agent y la IP convertida en hash (SHA-256 con una sal que rota cada día; la IP sin procesar no se guarda nunca). En la práctica, eso da tres respuestas en las que pueden apoyarse los scripts y los procedimientos:

• Confirmación de entrega: un evento viewed significa que la entrega se ha producido.
• Detección de anomalías: una ráfaga de failed_passphrase o una vista que no reconoces es la señal para rotar de inmediato.
• Un registro limpio para las revisiones: «entregado una vez, leído una vez, destruido» es una frase que gusta a los auditores.

Límites: lo que los enlaces no resuelven

• No son una bóveda. Un enlace de un solo uso no gestiona el acceso continuo, los calendarios de rotación ni el inventario de quién tiene qué.
• El enlace es la clave. LinkPilot cifra el texto en tu navegador y nunca recibe la clave, pero esa clave viaja en la parte del enlace que va después del #, así que cualquiera que consiga el enlace completo puede leer el secreto, y si el enlace se pierde, el secreto no se puede recuperar. Los archivos adjuntos se cifran de la misma manera, pero sus nombres y tamaños no. Una expiración corta y la destrucción tras la lectura siguen siendo importantes. Actualización del 29 de septiembre de 2026: este punto decía antes «no tienen cifrado de extremo a extremo», lo que era cierto hasta esa fecha. Los detalles están en la página de arquitectura de seguridad.
• No arreglan la dispersión de secretos en el código. Las claves escritas a mano en los repositorios necesitan escaneo y rotación, no un medio de entrega mejor.
• No pueden proteger el otro extremo. Cuando una persona ha leído el valor, da por hecho que vive allí donde lo haya guardado.

Lecturas relacionadas

• Cómo compartir claves de API de forma segura
• Enlaces que expiran: por qué importan los plazos cortos
• Arquitectura de seguridad de LinkPilot

Referencias

• GitHub Docs, Using secrets in GitHub Actions.
• Kubernetes, Secrets.
• jq, Manual.
• curl, Manual page, -d, --data.