Cómo decodificar un token JWT (Header, Payload, Signature)

Un JWT (JSON Web Token) es una cadena compacta con tres partes separadas por puntos: header.payload.signature. Cada parte (excepto la signature) se codifica en Base64URL y se puede decodificar para inspeccionar los claims. Decodificar un JWT NO verifica su firma: cualquiera puede crear un token con cualquier claim.

El Decodificador de JWT de NeatForge decodifica el header y el payload al instante y marca el estado de los claims iat, nbf y exp, todo en tu navegador.

¿Qué es un JWT?

Un JWT es un estándar abierto (RFC 7519) para transmitir claims entre partes en forma de objeto JSON. Se usa habitualmente para autenticación y autorización en APIs REST y aplicaciones web.

Un token se ve así: xxxxx.yyyyy.zzzzz

• Header: algoritmo y tipo de token.
• Payload: los claims (datos del usuario, roles, expiración).
• Signature: la firma que garantiza la integridad.

Los JWT son sin estado: el servidor no necesita consultar ninguna sesión porque los claims viajan dentro del propio token. Eso los hace ideales para APIs distribuidas, microservicios y aplicaciones móviles donde cada petición debe autenticarse por sí sola sin una búsqueda en base de datos.

¿Qué significan iat, nbf y exp?

Son claims de tiempo estándar, almacenados como marcas de tiempo Unix en segundos:

• iat (issued at): cuándo se creó el token.
• nbf (not before): fecha más temprana en la que es válido.
• exp (expiration): cuándo deja de ser válido.

Si exp ya pasó, el token está expirado. Si nbf aún no ha llegado, el token aún no es válido.

El decodificador compara estas marcas con el reloj de tu navegador y resalta en rojo los tokens expirados y en amarillo los que aún no son válidos. Un payload típico de un token de acceso de una hora se reconoce porque exp − iat = 3600: fue emitido para acompañar peticiones API durante sesenta minutos y después deja de funcionar por sí solo.

¿Qué es la codificación Base64URL?

Base64URL es una variante de Base64 pensada para URLs y JSON:

• usa - en lugar de +
• usa _ en lugar de /
• omite el relleno =

Esto evita caracteres que romperían una URL. Para más detalles, consulta nuestra guía sobre cómo codificar y decodificar Base64.

Solo el header y el payload se pueden decodificar: la signature no es JSON y no se “decodifica”, solo se verifica contra el secreto o la clave pública del emisor.

Decodificar vs verificar: la distinción clave

• Decodificar: leer el header y el payload sin comprobar la firma. Cualquiera puede hacerlo.
• Verificar: comprobar la signature con el secreto o la clave pública del emisor.

Nunca confíes en los claims de un JWT sin verificar la firma. Un token sin verificar es solo una afirmación, no una prueba.

En la práctica, la verificación ocurre en tu backend con una librería JWT consolidada: comprueba la firma, valida que el emisor (iss) y la audiencia (aud) sean los esperados y rechaza el token si la hora actual queda fuera del intervalo entre nbf y exp. La decodificación en el navegador sirve para depurar; la decisión de acceso siempre la toma el servidor.

Claims que encontrarás más allá de iat, nbf y exp

Los tokens reales llevan mucho más que marcas de tiempo. Estos cinco claims aparecen en la mayoría de los JWT de producción:

• iss (issuer): quién creó el token, normalmente una URL como https://auth.example.com. Tu API solo debería aceptar emisores de confianza.
• sub (subject): a quién pertenece el token, normalmente un ID de usuario como user_123. Es el valor que tu backend usa para cargar el registro correcto.
• aud (audience): para quién es el token, por ejemplo el ID de tu aplicación. Un token emitido para una app debe ser rechazado por otra, y eso es justo lo que aud garantiza.
• jti (JWT ID): identificador único por token, usado para listas de revocación y detección de tokens reproducidos.
• scope, roles o permissions: claims personalizados que describen lo que el portador puede hacer, por ejemplo read:orders o un array como ["admin", "billing"].

Un payload decodificado típico se ve así:

{
  "iss": "https://auth.example.com",
  "sub": "user_123",
  "aud": "mi-app",
  "iat": 1700000000,
  "exp": 1700003600,
  "scope": "read:orders write:orders"
}

Fíjate en que exp menos iat son 3600 segundos: es un token de acceso de una hora, la duración estándar para tokens que viajan con cada llamada API. Los tokens de refresco viven mucho más (días o semanas) y se guardan por separado, precisamente porque un token robado de una hora deja de funcionar solo.

Cómo solucionar tokens que fallan

Cuenta los puntos. Un JWT válido tiene exactamente dos puntos que separan tres segmentos. Los tokens pegados se rompen casi siempre porque un salto de línea, unos puntos suspensivos añadidos por el visor de logs o un mensaje de chat truncado se comieron la cola de la firma. Si cuentas menos de dos puntos, vuelve a copiar desde el origen.

Comprueba segundos frente a milisegundos. Si exp muestra una fecha decenas de miles de años en el futuro, el emisor generó milisegundos en lugar de segundos. Un valor de 13 dígitos como 1700000000000 dividido entre 1000 da el valor correcto de 10 dígitos en segundos. Pega cualquier marca sospechosa en el Convertidor de Timestamp para ver la fecha legible al instante.

Ten en cuenta el desfase de relojes. Un aviso de “aún no válido” en un token recién creado suele significar que el servidor emisor va segundos o minutos por delante de tu máquina. Las librerías de backend lo resuelven con un margen de tolerancia, normalmente de 30 a 60 segundos, aplicado tanto a nbf como a exp. Si controlas el código de validación, añade ese margen en lugar de exigir una sincronización perfecta entre máquinas.

Sospecha del segmento equivocado. A veces se pega solo el segmento del payload o una clave API adyacente en lugar del token completo. Cada segmento por separado es Base64URL válido, así que un decodificador Base64 puede decodificarlo sin problema mientras el decodificador JWT se queja. Copia siempre desde el primer carácter del header hasta el último carácter de la firma.

¿Cómo decodificar un JWT de forma segura?

1. Abre el Decodificador de JWT.
2. Pega el token en la caja de entrada.
3. Revisa el header y el payload como JSON formateado.
4. Comprueba el estado de iat, nbf y exp.

No pegues tokens de producción en sitios no confiables; usa herramientas locales para datos sensibles.

Nota de privacidad

La decodificación ocurre completamente en tu navegador. El token nunca se envía a un servidor ni se almacena. Aun así, evita compartir JWTs en capturas de pantalla o tickets de soporte.

Los tokens pueden contener IDs de usuario, correos y ámbitos de permiso, así que trátalos como credenciales: si pegas por error un token activo en un chat o una incidencia, revócalo y genera uno nuevo. Para depurar en equipo, pide tokens de prueba de corta duración en lugar de reutilizar los de producción.

Preguntas frecuentes

¿Esta herramienta verifica la firma del JWT? No. Solo decodifica. La verificación requiere el secreto de firma o la clave pública, que el cliente no tiene.

¿Es seguro pegar mi JWT aquí? Sí, porque todo es local. Pero evita pegar tokens muy sensibles en sitios de terceros; para esos casos usa una herramienta offline.

¿Por qué mi token tiene tres partes? Porque un JWT sigue el formato header.payload.signature. Las dos primeras son JSON codificado en Base64URL; la tercera es la firma criptográfica.

→ Decodifica tu JWT gratis