Cómo decodificar un JWT: estructura y fecha de exp

Contenido
Una cadena JWT (JSON Web Token) no está cifrada, sino codificada. De las tres partes separadas por puntos (.), las dos primeras (header y payload) son simplemente texto JSON codificado en base64url, así que basta con decodificarlas para leer su contenido tal cual, sin necesidad de ninguna clave secreta.
Este artículo explica cómo comprobar esa estructura con tus propios ojos y cómo valores de tiempo como exp e iat se guardan como números y se convierten en fechas.
Resumen ① Un JWT es una cadena en la que las tres partes header.payload.signature se unen con puntos (.), y header y payload son, cada una, JSON codificado en base64url. ② Decodificar base64url no descifra nada: solo revierte la codificación, por lo que cualquiera puede leer el contenido de header y payload sin clave secreta. ③ Los valores de tiempo como exp e iat son marcas de tiempo Unix que indican los segundos transcurridos desde 1970-01-01 00:00:00 (UTC), y hay que multiplicarlos por 1000 para obtener una fecha en milisegundos de JavaScript.
Cuándo te topas con este problema
Es habitual que la respuesta de una API de inicio de sesión incluya un único campo, como access_token, con una cadena larga. Esa cadena que empieza por eyJhbGci... parece un código cifrado ilegible, y es fácil pensar que no hay forma de ver qué contiene.
En realidad, dentro de esa cadena están tal cual el identificador de usuario (sub), la información de permisos y valores como cuándo se emitió el token (iat) y cuándo caduca (exp). Cuando investigas problemas del tipo «la sesión se cierra todo el rato» o «los permisos se aplican de forma rara», abrir directamente los valores del token te ayuda a acotar la causa.
Cómo decodificar a mano, sin herramientas
Un JWT es una sola cadena con tres partes, header.payload.signature, separadas por un punto (.). Qué contiene cada parte y cómo está codificada se resume a continuación.
| Parte | Qué contiene | Codificación | ¿Se puede parsear directamente como JSON? |
|---|---|---|---|
| Header | El tipo de token (typ) y el algoritmo de firma (alg) | base64url | Sí |
| Payload | Claims como sub, iat y exp | base64url | Sí |
| Signature | El resultado de firmar header+payload con la clave secreta | base64url | No (son bytes, no formato JSON) |
La razón por la que solo la signature no se puede parsear como JSON es que ese valor no es texto JSON en origen, sino el valor de bytes puro que genera el algoritmo de firma. Está codificado en base64url igual que header y payload, pero al decodificarlo no aparece texto legible para una persona.
base64url es algo distinto del base64 estándar. Para que se pueda usar tal cual en URL o en rutas de archivo, cambia "+" por "-" y "/" por "_", y normalmente omite el relleno "=" del final. Por eso, para decodificar hay que revertir primero esas sustituciones.
Si ejecutas el siguiente código en la consola de las herramientas de desarrollo del navegador (F12), puedes ver header y payload directamente sin ninguna herramienta adicional.
function base64UrlDecode(str) {
str = str.replace(/-/g, "+").replace(/_/g, "/");
while (str.length % 4) str += "=";
const binary = atob(str);
return decodeURIComponent(
binary.split("").map(c => "%" + c.charCodeAt(0).toString(16).padStart(2, "0")).join("")
);
}
const [header, payload] = token.split(".");
console.log(JSON.parse(base64UrlDecode(header)));
console.log(JSON.parse(base64UrlDecode(payload)));
La razón de pasar por decodeURIComponent y charCodeAt es que el resultado de atob() contiene los bytes UTF-8 directamente como caracteres. Si el payload incluye caracteres no ASCII, como un nombre en coreano, al hacer JSON.parse del resultado de atob() directamente pueden aparecer caracteres corruptos.
Una vez que tienes el payload, también puedes convertir tú mismo los valores exp e iat a fechas. Ambos están en segundos, así que multiplícalos por 1000 para pasarlos a milisegundos y mételos en un objeto Date.
new Date(payload.exp * 1000).toLocaleString();
Compruébalo con nuestra herramienta.
La decodificación se hace solo en tu navegador y no se envía nada al servidor. No se verifica la firma.

Puntos que suelen confundirse
Decodificar y verificar la firma son tareas distintas. En la siguiente tabla se diferencian.
| Aspecto | Decodificación | Verificación de firma |
|---|---|---|
| Qué hace | Revierte base64url y lee el JSON | Recalcula la firma con la clave secreta o pública y la compara |
| Qué necesita | Solo la cadena del token | La clave secreta o la clave pública usada en la firma |
| Qué permite saber | Lo que dice el header y el payload | Si ese contenido se ha manipulado desde su emisión |
Es decir, decodificar es «leer el contenido» y verificar la firma es «comprobar que ese contenido no se ha manipulado». Ambas tareas requieren materiales distintos y persiguen fines distintos, y el hecho de haber leído header y payload no significa que la firma esté verificada.
exp, iat, nbf y auth_time son todos marcas de tiempo Unix en segundos. Como Date de JavaScript trabaja en milisegundos, si pasas el valor tal cual a new Date() sin multiplicarlo por 1000 obtendrás una fecha absurda cerca del 1 de enero de 1970.
No todos los tokens incluyen iat, exp, nbf y auth_time. Como el emisor incluye solo los claims que necesita, que un token no tenga exp no es un error en sí mismo.
En resumen
- Un JWT es una cadena en la que las tres partes header.payload.signature se unen con puntos, y solo header y payload son JSON codificado en base64url.
- La signature no es JSON, sino el valor de bytes que genera el algoritmo de firma, así que al decodificarla no se lee como texto.
- Decodificar base64url solo revierte la codificación, por lo que cualquiera puede leer header y payload sin clave secreta, y eso no es cifrado.
- Los valores de tiempo como exp e iat son marcas de tiempo Unix en segundos, así que hay que multiplicarlos por 1000 para obtener una fecha de JavaScript.
- Decodificar y verificar la firma son tareas distintas, y solo decodificando no se puede comprobar si el token se ha manipulado.
La decodificación se hace solo en tu navegador y no se envía nada al servidor. No se verifica la firma.
Preguntas frecuentes
¿Se puede decodificar también la signature para verificarla?
No. La signature es el valor de bytes resultante de firmar header y payload juntos con la clave secreta, no está en formato JSON y, al decodificarla en base64url, no aparece texto con sentido. Para comprobar si la firma es válida hace falta un procedimiento de verificación aparte: recalcular la firma con la clave secreta (o la clave pública) usada al emitir el token y compararla.
¿Qué pasa con un token que no tiene exp?
Que no exista el claim exp significa que no hay un criterio para determinar si ha caducado. Solo cuando hay exp se puede comparar ese valor con la hora actual y mostrar si es válido o ha caducado; los tokens sin exp quedan fuera de esa comparación.
¿El token que introduzco se envía al servidor?
No. Todo el proceso de decodificación que convierte header y payload en JSON se ejecuta dentro del navegador, y la cadena del token que introduces no se envía al servidor ni se guarda. Eso sí, el payload no está cifrado de origen, así que si haces una captura de pantalla o lo compartes, su contenido también queda expuesto.
¿Qué significan iat, nbf y auth_time?
iat (issued at) es el momento en que se emitió el token, y nbf (not before) es el momento a partir del cual el token pasa a ser válido, es decir, antes de esa hora no lo es. auth_time es el valor que indica cuándo completó el usuario realmente la autenticación (el inicio de sesión), y se usa junto a los otros en estructuras donde el momento del inicio de sesión y el de emisión del token pueden ser distintos.
Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano