JWT explicado: cómo funcionan los JSON Web Tokens (con ejemplos)

¿Qué es un JWT?

Un JSON Web Token (JWT) es un token compacto que sirve para demostrar quién eres ante una API. Cuando inicias sesión, el servidor te entrega un JWT; tu navegador o tu app lo envía después en cada petición, normalmente en la cabecera Authorization: Bearer .... El servidor lo comprueba y sabe quién llama — sin buscar una sesión en la base de datos.

Los JWT están en todas partes: aplicaciones web de una sola página, apps móviles, OAuth y OpenID Connect (inicio de sesión con Google, Microsoft, Auth0) y comunicación entre microservicios.

Las tres partes de un JWT

Un JWT parece una cadena larga con dos puntos:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0IiwibmFtZSI6IkFsaWNlIiwicm9sZSI6ImFkbWluIiwiaWF0IjoxNzU3NDk0MDAwLCJleHAiOjE3NTc0OTc2MDB9.signature

Cada parte está codificada en Base64URL:

1. La cabecera (header) — el algoritmo y el tipo de token.
2. La carga útil (payload) — los claims: quién es el usuario, cuándo caduca el token…
3. La firma — demuestra que el token no se ha modificado.

Decodificadas, las dos primeras partes son JSON sencillo:

{ "alg": "HS256", "typ": "JWT" }

{
  "sub": "1234",
  "name": "Alice",
  "role": "admin",
  "iat": 1757494000,
  "exp": 1757497600
}

Los claims estándar

Claim	Nombre	Significado
iss	Issuer	Quién emitió el token (tu servidor de autenticación)
sub	Subject	A quién se refiere el token (normalmente el ID de usuario)
aud	Audience	A qué API va destinado el token
exp	Expiration	Cuándo deja de ser válido (timestamp Unix)
iat	Issued at	Cuándo se creó el token
nbf	Not before	El token no es válido antes de esta fecha
jti	JWT ID	Identificador único, útil para revocarlo

Las fechas son timestamps Unix (segundos desde el 1 de enero de 1970). Para leerlas, usa el conversor de timestamp Unix — o deja que el decodificador JWT lo haga por ti.

Cómo funciona la firma

El servidor calcula la firma a partir de la cabecera, la carga útil y una clave secreta (HS256) o una clave privada (RS256, ES256). Si alguien cambia un solo carácter de la carga útil — por ejemplo, "role": "user" por "role": "admin" — la firma deja de coincidir y el servidor rechaza el token.

La firma garantiza, por tanto, la integridad (el token no se ha modificado) y la autenticidad (lo emitió alguien que tiene la clave). No oculta el contenido.

Decodifica un JWT

El decodificador JWT muestra la cabecera, la carga útil, los claims y la fecha de caducidad de forma legible. Funciona por completo en tu navegador: el token nunca se envía a un servidor.

El decodificador no verifica la firma: para eso haría falta el secreto o la clave pública, que no deben estar en una herramienta del navegador. La verificación la tiene que hacer tu servidor.

Errores de seguridad habituales

1. Guardar datos sensibles en la carga útil — cualquiera puede leerla.
2. Tokens que nunca caducan — fija un exp corto (de 15 minutos a 1 hora) y usa refresh tokens.
3. Aceptar alg: none — impón siempre el algoritmo esperado en el servidor.
4. Un secreto HS256 débil — usa un secreto largo y aleatorio (al menos 256 bits); genera uno con el generador de contraseñas.
5. Guardar el token en localStorage sin pensarlo — vulnerable a XSS; una cookie HttpOnly suele ser más segura en apps web.
6. Pegar tokens de producción en cualquier web — un token válido es una llave de la cuenta. Usa una herramienta que funcione en local y mejor con tokens caducados o de prueba.

Conclusión

Un JWT no es más que tres bloques Base64URL: una cabecera, una carga útil legible y una firma que la protege de modificaciones. Entender esta estructura te permite depurar un problema de autenticación en segundos — y evitar los errores de seguridad que convierten un token práctico en una vulnerabilidad.