Que hay dentro de un JWT? Cabecera, payload y firma (2026)

Un JSON Web Token (JWT) parece una cadena larga y aleatoria, pero solo son tres trozos de datos pegados con puntos. El primero dice como se construyo el token. El segundo son los claims: para quien es, cuando caduca y lo que el emisor haya metido. El tercero es una firma que un servidor de confianza puede comprobar. Esta guia recorre cada parte, los claims que veras a diario y la diferencia entre leer un token y fiarte de el. Para inspeccionar uno de verdad, pegalo en el Decodificador JWT: corre en el navegador y no sube el valor.

Tres partes unidas por puntos

RFC 7519 define un JWT compacto como tres segmentos Base64URL separados por un punto. No hay envoltorio extra, no hay JSON por fuera y casi nunca hay signos igual de relleno. Si partes por . siempre obtienes tres cadenas, aunque la ultima este vacia (la forma no segura alg none).

• Cabecera: metadatos del token, casi siempre JSON con alg y typ.
• Payload: los claims. Esto es lo que las APIs leen de verdad.
• Firma: una etiqueta criptografica sobre cabecera y payload. Este articulo y la herramienta la tratan como bytes opacos.

Cualquiera que sepa escribir JSON puede inventar una cabecera y un payload y codificarlos en Base64URL. Por eso las dos primeras partes son publicas. Quien intercepte un JWT puede leer esos claims. Los datos confidenciales no caben en un JWT salvo que tambien lo cifres (JWE), que es otro formato.

La cabecera

La cabecera dice a los verificadores como tratar el token. Es un objeto JSON pequeno. Tras decodificar el primer segmento en Base64URL sueles ver:

• alg - el algoritmo de firma (o none). Valores habituales: HS256 (HMAC con secreto compartido), RS256 o ES256 (claves asimetricas).
• typ - casi siempre JWT. Algunos emisores lo omiten.
• kid - id de clave opcional para que el servidor elija la clave publica correcta de un JWKS.
• cty - tipo de contenido, raro, cuando el payload es un JWT anidado.

El campo peligroso es alg. Un decodificador mostrara lo que el token declare. Un verificador ingenuo que acepte alg none, o que deje a un atacante cambiar RS256 por HS256 y firmar con la clave publica como si fuera un secreto HMAC, aceptara tokens falsos. Eso es un error de servidor, no algo que un decodificador en el navegador pueda arreglar. Lee alg como pista, nunca como prueba.

El payload (claims)

El payload es otro objeto JSON. Las especificaciones JWT separan claims registrados (un vocabulario pequeno compartido) y nombres privados o publicos que define tu app. Las marcas de tiempo son NumericDate: segundos desde 1970-01-01 UTC, no milisegundos.

Claims registrados que veras a menudo

• iss - emisor. Quien creo el token (una URL o el nombre del servidor de auth).
• sub - sujeto. El usuario o servicio del que habla el token.
• aud - audiencia. La API o app que deberia aceptarlo. Puede ser texto o una lista.
• exp - caducidad. Rechaza el token despues de este tiempo Unix.
• nbf - no antes de. Rechaza el token antes de este tiempo Unix.
• iat - emitido en. Cuando lo creo el emisor.
• jti - id del JWT. Un id unico para revocar o deduplicar tokens.

Claims propios

Todo lo demas es dato de la aplicacion: name, email, role, scope, tenant o un array de permisos. Son comodos para las APIs y tambien triviales de falsificar si solo decodificas. Un claim role: admin en un token que pegaste en un decodificador significa que el emisor (o un atacante) escribio esa cadena. No es un permiso hasta que el backend verifica la firma y comprueba iss, aud y exp.

La firma

El tercer segmento no es JSON. En HS256 es un HMAC-SHA256 sobre la cadena ASCII header.payload con un secreto compartido. En RS256 o ES256 es una firma asimetica sobre la misma entrada. El decodificador muestra el texto Base64URL en crudo para que compares tokens; nunca recalcula ni comprueba esa etiqueta. Verificar necesita el secreto o la clave publica del emisor, y debe ocurrir en una maquina de confianza.

Base64URL, no Base64 normal

La cabecera y el payload de un JWT usan Base64URL (RFC 4648): la misma codificacion de 6 bits que Base64, pero + pasa a -, / pasa a _ y el relleno = suele omitirse. Asi el token viaja bien en query strings y cabeceras. Si pegas un segmento JWT en una herramienta Base64 generica, restaura primero los caracteres URL o el JSON no saldra. El Codificador / decodificador Base64 es para Base64 normal; la herramienta JWT ya aplica el alfabeto URL.

Ejemplo trabajado

El token de demo clasico de la documentacion JWT se decodifica a una cabecera y un payload minimos. Tras partir por puntos y decodificar las dos primeras partes en Base64URL obtienes:

• JSON de cabecera: {"alg":"HS256","typ":"JWT"}
• JSON de payload: {"sub":"1234567890","name":"John Doe","iat":1516239022}
• iat 1516239022 es 2018-01-18 01:30:22 UTC: el token lleva anos caducado si hubiera tenido exp.
• El tercer segmento es la firma HMAC. Mirarla no dice si el secreto era correcto.

Un prefijo Bearer no forma parte del JWT. Authorization: Bearer eyJ... es una convencion de cabecera HTTP. Quita Bearer y el espacio, luego decodifica los tres segmentos. El decodificador de ToolsMinify lo hace por ti.

Lo que puedes leer frente a lo que el servidor debe comprobar

Usa un decodificador cuando depuras. Usa un verificador cuando autorizas.

1. Puedes leer alg, typ y kid para ver que clave pretendia el emisor.
2. Puedes leer sub, email o role para entender una peticion que falla.
3. Puedes comparar exp e iat con el reloj para ver si el token esta viejo.
4. Un servidor debe verificar la firma con la clave y el algoritmo correctos.
5. Un servidor debe rechazar tokens con iss o aud incorrectos, y tokens que aun no valen o ya caducaron.
6. Un servidor debe tratar cada claim como no fiable hasta que esos chequeos pasen.

Errores habituales

• Fiarte de claims vistos en un decodificador. Cualquiera puede montar header.payload y dejar una firma basura.
• Aceptar alg none o dejar que el token elija el algoritmo de verificacion.
• Meter contrasenas, secretos de sesion o datos personales en el payload. El payload lo lee quien tenga el token.
• Pegar tokens de produccion en un sitio al azar. Prefiere un decodificador en el cliente para que el token no salga de la maquina.
• Confundir este formato con JWT cifrados (JWE). Un JWE compacto tiene cinco segmentos, no tres.

Preguntas frecuentes

Un JWT va cifrado?

Un JWT firmado estandar (JWS) no va cifrado. Cabecera y payload solo estan codificados. Quien tenga el token puede leer los claims. Los tokens cifrados usan JWE y se ven distintos. Si pegas un token en un decodificador y ves JSON, no era confidencial.

Por que el decodificador no verifica la firma?

Verificar necesita un secreto o la clave publica de quien guarda la privada. Meter eso en una pagina publica seria inseguro, y un sello verde de "valido" en un sitio que no controlas ensena a fiarse del chequeo equivocado. Decodifica en local; verifica en tu API.

Que significa alg none?

Significa que el emisor (o un atacante) marco el token como no seguro. El tercer segmento esta vacio. Un decodificador aun puede mostrar cabecera y payload. Una API de produccion deberia rechazar alg none salvo que tengas una razon local y explicita para aceptar tokens sin firma.

exp e iat van en milisegundos?

No. Los NumericDate de JWT son segundos desde el epoch Unix. Si un claim parece 1.7e12 probablemente estas viendo Date.now() de JavaScript en milisegundos por error.

Puedo reconstruir un token despues de editar el payload?

Puedes volver a codificar el JSON a Base64URL y unir tres segmentos, pero la firma antigua ya no coincidira. Sin el secreto o la clave privada del emisor el token nuevo esta falsificado. Es lo esperado. Los decodificadores sirven para leer, no para emitir tokens de produccion.

Donde inspecciono un token con seguridad?

Usa una pagina que decodifique en el navegador y no suba la cadena. El Decodificador JWT de ToolsMinify lo hace. Para la guia paso a paso, Como usar el Decodificador JWT.

Inspecciona un token en el navegador

Pega un JWT para ver cabecera, payload y firma en secciones legibles. Nada se sube:

• Decodificador JWT - parte el token, formatea el JSON de cabecera y payload, copia cada parte.
• Como usar el Decodificador JWT - guia paso a paso de la misma herramienta.
• Codificador / decodificador Base64 - Base64 normal, no el alfabeto URL de JWT.
• Generador de hash - Checksums SHA-256 en el navegador. No firma JWT.
• Todas las herramientas de desarrollo - el indice completo de la categoria.