Tipos de token: API Key, JWT, PAT y OAuth
Uno token es un fragmento de texto secreto que demuestra quién eres ante un servicio. En vez de escribir tu usuario y contraseña cada vez, presentas el token y la puerta se abre. Hay varios tipos, cada uno para una situación. Saber cuál usar evita dolores de cabeza y mantiene todo más seguro.
🔑 Clave de API
Una clave simple y fija, como sk_live_a1B2c3.... Identifica la aplicación, no a un usuario. Es ideal para servicios como el envío de correo electrónico, mapas o IA. Cuándo usar: integración sencilla máquina a máquina.
🎫 JWT
"JSON Web Token". Un token firmado que lleva información (quién es el usuario, hasta cuándo es válido) dentro de sí mismo. Tiene un plazo de validez corto. Cuándo usar: sesiones de inicio de sesión en aplicaciones web y móviles.
👤 PAT
"Personal Access Token". Una clave personal que actúa en tu nombre (ej.: un token de GitHub para hacer push). Reemplaza la contraseña en scripts y herramientas. Cuándo usar: automatización en tu nombre, como deploy mediante CI.
🔗 OAuth
No es un token único, sino un flujo. El usuario hace clic en "Entrar con Google" y autoriza tu app sin darte nunca la contraseña. Al final, recibes un token de acceso. Cuándo usar: inicio de sesión social y acceso a datos de terceros.
🧠 Analogía: las llaves de un hotel
Piensa en un hotel grande:
- •Clave de API = la llave maestra de servicio de la cafetería: abre todo lo de ese sector, siempre es la misma.
- •JWT = la tarjeta magnética de la habitación: sirve solo por unos días y después deja de funcionar.
- •PAT = la llave de tu casillero personal: es tuya y actúa en tu nombre.
- •OAuth = el valet: le das la llave del auto por un instante y lo estaciona, sin convertirse en el dueño del auto.
Guardar tokens en el servidor de forma segura
Tener el token es solo la mitad del trabajo. La otra mitad es dónde guardar. La regla de oro: el token nunca queda escrito en el código. Va en un archivo separado, el .env, que solo puede leer el servidor y que Git ignora.
El archivo .env
Un archivo de texto simple, en formato CHAVE=valor, uno por línea:
# Crear y editar el archivo en el servidor
$ nano .env
# Dentro de él, tus claves:
DATABASE_URL=postgres://user:senha@host/db
API_KEY=sk_live_a1B2c3d4e5
JWT_SECRET=um-segredo-bem-longo-e-aleatorio
Bloqueando el archivo: chmod 600
De forma predeterminada, otros usuarios del servidor pueden leer tus archivos. El comando chmod 600 dice: "solo el dueño puede leer y escribir; nadie más".
# Ver los permisos actuales
$ ls -l .env
-rw-r--r-- 1 deploy deploy 180 jun 16 10:00 .env
# Restringir: solo el propietario puede leer y escribir
$ chmod 600 .env
$ ls -l .env
-rw------- 1 deploy deploy 180 jun 16 10:00 .env
👁 Qué vas a ver en la pantalla
Lee la letra pequeña de ls -l. Las primeras 10 indican quién puede modificar el archivo:
-rw------- (después de chmod 600)
# rw- = el propietario puede leer y escribir
# --- = el grupo no puede hacer nada
# --- = los demás no pueden hacer nada
Si todavía aparece -rw-r--r--, cualquiera en el servidor puede leerlo. Ejecuta chmod.
⚠️ Error común
Problema: "Subí mi proyecto a GitHub y el token quedó expuesto públicamente."
Solución: O .env fue al repositorio porque no estaba en el .gitignore. Agrega la línea .env al .gitignore ANTES del primer commit. Si ya se filtró, considera que el token está comprometido: revócalo y genera otro (ver tema 3). Borrar el archivo no basta, sigue en el historial.
Rotación y vencimiento: cambiar antes del problema
Un token que nunca cambia es una bomba de tiempo. Cuanto más tiempo esté vigente, más posibilidades hay de que se filtre (en un log, una captura de pantalla, un backup antiguo). Rotar y generar una clave nueva cada cierto tiempo y descartar la anterior. Expiración y que el token caduque automáticamente después de un plazo.
🧠 Analogía: cambiar la cerradura
Cuando pierdes una llave de casa, no rezas para que nadie la encuentre: cambias la cerradura. Rotar un token es la misma idea, pero de forma preventiva, cada cierto tiempo, incluso sin tener la certeza de que se filtró. Así, si algún día aparece una copia de la llave antigua por ahí, ya no abre nada.
El ciclo de rotación, paso a paso
Genera la clave nueva
En el panel del servicio, crea un token nuevo. Todavía no elimines el anterior.
Actualiza el servidor
Cambia el valor en el .env y reinicia la aplicación.
$ nano .env
# Reemplaza API_KEY por el valor nuevo y guarda
$ systemctl restart minha-app
Confirma que funciona
Prueba la app con la nueva clave. Avanza solo si todo está bien.
Revoca la clave anterior
Ahora sí, elimina el token antiguo en el panel. La cerradura vieja ya no abre.
⚠️ Error común
Problema: "Revoké el token antiguo y el sitio dejó de funcionar."
Solución: Revocaste la clave anterior antes de confirmar que la nueva funcionaba. Sigue siempre este orden: genera una nueva, actualízala, pruébala y SOLO ENTONCES revoca la anterior. Mantener ambas válidas durante un período breve evita interrumpir el servicio en medio del cambio.
✓ Qué HACER
- ✓Definir un plazo (ej.: cambiarla cada 90 días)
- ✓Revocar de inmediato cualquier token filtrado
- ✓Preferir tokens con expiración automática
✗ Qué NO hacer
- ✗Usar la misma clave durante años sin cambiarla
- ✗Ignorar una filtración "porque parece pequeña"
- ✗Revocar la anterior antes de probar la nueva
Secrets Managers: La bóveda profesional
O .env resuelve bien para un servidor. Pero cuando tienes varios servidores, varias personas en el equipo y decenas de secretos, copiar archivos a mano se vuelve una pesadilla. Ahí es donde entran los administradores de secretos: programas dedicados a guardar y entregar secretos de forma segura.
👁 Qué vas a ver en la pantalla
En vez de abrir un archivo, pides el secreto mediante un comando y aparece al instante (y queda registrado quién lo pidió):
# Ejemplo con Vault
$ vault kv get secret/minha-app
==== Datos ====
API_KEY sk_live_a1B2c3d4e5
# Ejemplo con Doppler
$ doppler secrets get API_KEY --plain
sk_live_a1B2c3d4e5
🛡 Vault (HashiCorp)
Bóveda robusta y open source. Guarda secretos, controla quién accede a cada uno e incluso puede generar credenciales temporales que vencen automáticamente. Es más potente, pero requiere más configuración.
📦 Doppler
Servicio más sencillo y fácil de usar. Centralizas los secretos en un panel y este los inyecta en tus apps y entornos. Un excelente punto de partida para equipos pequeños.
🧠 Analogía: la caja fuerte del banco
Guardar dinero debajo del colchón (el .env (suelto) funciona hasta cierto punto. Un secrets manager es la bóveda del banco: un solo lugar, con una puerta blindada, que registra cada vez que alguien entra y hasta puede tener llaves que solo funcionan durante un día. No guardas el secreto real en tu máquina; se lo pides a la bóveda cuando lo necesitas.
💡 Consejo: empieza de forma sencilla
Para un proyecto personal en un solo VPS, el .env con chmod 600 ya está muy bien. Adopta un secrets manager solo cuando lo necesites: muchos entornos, mucha gente o demasiados secretos para controlar a mano. La herramienta adecuada para cada escala.
Auditoría: quién usó qué y cuándo
De nada sirve bloquearlo todo si no puedes ver qué pasó. Auditoría de acceso y mantener un registro (log) de cada uso: qué token, qué acción, de dónde y a qué hora. Cuando algo sale mal, esos logs son tu cámara de seguridad.
Leyendo un log de acceso
Cada línea cuenta una historia: quién, cuándo, qué y cuál es el resultado.
# Ver los últimos accesos registrados
$ tail -n 5 /var/log/minha-app/access.log
10:01 token=deploy acao=push ip=200.1.1.5 ok
10:04 token=backup acao=read ip=200.1.1.5 ok
10:09 token=deploy acao=delete ip=45.9.9.9 ok
10:12 token=deploy acao=delete ip=45.9.9.9 FALHA
Observa la línea 3: el token deploy borró algo desde una IP extraña (45.9.9.9). Señal de alerta.
👁 Qué vas a ver en la pantalla
Para investigar un token específico, filtra el log. El grep muestra solo las líneas que interesan:
$ grep "token=deploy" access.log
10:01 token=deploy acao=push ip=200.1.1.5 ok
10:09 token=deploy acao=delete ip=45.9.9.9 ok
# Filtrar solo los errores
$ grep "FALHA" access.log
10:12 token=deploy acao=delete ip=45.9.9.9 FALHA
🧠 Analogía: el libro de visitas del edificio
Un edificio bien cuidado tiene portero y libro de registro: nombre, hora de entrada y salida de cada visitante. Si desaparece algo, consultas el libro y descubres quién pasó. El registro de acceso es ese libro de visitas de tus tokens. Sin él, solo descubres que te robaron, nunca quién lo hizo.
💡 Consejo: nunca registres el secreto en sí
En el registro, anota el nombre del token (p. ej.: token=deploy), nunca el valor completo. Si escribes la clave entera en el log, el propio registro de seguridad se convierte en una filtración. Mucha gente suele leer los logs.
Buenas prácticas: mínimo privilegio y un token por servicio
Al reunirlo todo, dos reglas sostienen el resto: menor privilegio (cada token solo puede hacer lo mínimo que necesita) y un token por servicio (nunca compartas la misma clave entre cosas diferentes). Si sigues esto, una filtración será un rasguño, no una catástrofe.
🧠 Analogía: el llavero del conserje
Imagina un edificio donde una sola llave abre TODAS las puertas: apartamentos, caja fuerte, garaje. Si cae en la calle, se acabó. Un edificio bien administrado le da a cada persona solo la llave de SU puerta. ¿Perdiste una? Cambias solo esa cerradura. Los tokens funcionan igual: uno por servicio, cada uno con el mínimo de permisos.
✓ Qué HACER
- ✓Un token para cada servicio (deploy, backup, monitor)
- ✓Dar solo el permiso necesario (lectura, si no necesita escribir)
- ✓Ponerle al token un nombre claro (token-backup-diario)
- ✓Revocar de inmediato los tokens de quien dejó el equipo
✗ Qué NO hacer
- ✗Una clave de "administrador total" usada para todo
- ✗Enviar el token por WhatsApp o correo electrónico sin cuidado
- ✗Dejar activos los tokens de exempleados
- ✗Pegar el token directamente en el código "solo para probar rápido"
Ejemplo: separando por servicio en el .env
# Cada servicio, su propia clave con su nombre
DEPLOY_TOKEN=ghp_xxxxx # solo hace push, nada más
BACKUP_TOKEN=bk_yyyyy # so leitura do banco
EMAIL_API_KEY=re_zzzzz # solo envía correo
# Si EMAIL_API_KEY se filtra, el deploy y la copia de seguridad siguen siendo seguros
🏆 Llegaste al final de la Trilha 3
Contrataste un VPS, te conectaste por SSH, cerraste los puertos con un firewall y ahora sabes gestionar las claves de tus servicios. Tienes un servidor propio, seguro y bajo control. En la próxima trilha, pondrás tus aplicaciones a funcionar dentro de él de forma organizada, con Docker y automatización.
📚 Resumen del módulo
Siguiente ruta:
Ruta 4 - Docker y automatización (empaqueta y ejecuta tus aplicaciones en el servidor de forma organizada)