Base64URL y JWT: cómo decodificar tokens, evitar errores y entender qué datos estás exponiendo
JWT (JSON Web Token) es un estándar muy usado para autenticación y autorización en APIs modernas. Un JWT normalmente tiene el formato header.payload.signature y las dos primeras partes están codificadas en Base64URL (no Base64 estándar). Esto causa confusión y errores típicos al intentar “leer” el token. En esta guía aprenderás:
- Qué es Base64URL y por qué existe
- Cómo decodificar un JWT correctamente
- Errores comunes (padding, caracteres, copy/paste)
- Buenas prácticas de seguridad (lo que nunca debes poner en el payload)
- Cómo usar Base64URL en integraciones reales (URLs, cookies, headers)
Para decodificar header/payload rápidamente, usa el conversor Base64/Base64URL del portal (incluye modo Base64URL).
Base64 vs Base64URL: diferencias reales
Base64URL es una variante diseñada para ser segura en URLs y tokens. Cambia el alfabeto de Base64 estándar para evitar caracteres problemáticos.
- Base64 usa
+y/ - Base64URL usa
-y_ - Base64 suele incluir padding
= - Base64URL normalmente elimina el padding
=
Esto es clave: si intentas decodificar Base64URL con un decodificador Base64 “normal”, puedes obtener errores o resultados inválidos. Además, en URLs el + puede interpretarse como espacio y el / puede interferir con rutas, por eso Base64URL es preferible.
Estructura de un JWT
Un JWT típico se ve así:
xxxxx.yyyyy.zzzzz- Header (Base64URL): indica algoritmo (
alg) y tipo (typ) - Payload (Base64URL): claims (por ejemplo
sub,exp,iss, roles) - Signature: firma criptográfica para validar integridad
Lo importante: “leer” no es “validar”
Puedes decodificar header/payload sin la clave, porque no están cifrados. Eso no implica inseguridad, siempre que la API verifique la firma correctamente. El gran error es confiar en el contenido del payload sin validar la firma. Un atacante podría fabricar un token si el backend no valida firma o permite algoritmos inseguros.
Cómo decodificar un JWT correctamente (paso a paso)
1) Separar el token
Copia el token y sepáralo por puntos. Te interesan:
- Parte 1: header
- Parte 2: payload
2) Decodificar con Base64URL
Ahora debes decodificar esas partes como Base64URL. En la práctica, Base64URL implica sustituir caracteres y, si tu librería lo requiere, restaurar el padding. Con nuestra herramienta solo activas Base64URL y pegas la cadena:
3) Leer el JSON resultante
El resultado es JSON. En payload, presta atención a:
exp: expiración (epoch). Útil para ver si el token ya expiró.iat: emisión.nbf: “not before”. No aceptar tokens antes de ese instante.iss: issuer.aud: audiencia.sub: sujeto/usuario.
Errores comunes al decodificar Base64URL/JWT
Error 1: “Invalid character”
Causa: usar Base64 estándar o copiar mal (espacios, comillas, saltos de línea). Solución: limpia la entrada y usa Base64URL. La herramienta del portal ignora espacios.
Error 2: padding faltante (=) y la librería falla
Base64URL suele venir sin padding. Algunas librerías exigen que la longitud sea múltiplo de 4. Solución: restaurar padding añadiendo = hasta completar, o usar un conversor que lo haga automáticamente.
Error 3: el payload tiene caracteres raros
Si el JSON sale corrupto, puede ser que la cadena esté truncada o que en realidad no sea JWT. También puede ser que estés decodificando la firma por error. Asegúrate de tomar solo header/payload.
Error 4: el token es válido “en local” pero falla en servidor
Esto suele deberse a diferencias en el reloj (clock skew) o validaciones de aud/iss. Decodificar ayuda a ver claims, pero recuerda: el servidor valida firma y claims, no solo la estructura.
Seguridad: qué NO debes poner en el payload
Como header/payload se pueden decodificar fácilmente, evita incluir información sensible:
- Contraseñas
- Tokens de terceros
- Datos personales sensibles (PII) que no deberían ser visibles
- Información financiera
- Direcciones, teléfonos o números de documento (si no es imprescindible)
Si necesitas confidencialidad, JWT (JWS) no es suficiente: considera cifrado (JWE) o un diseño donde el token sea un identificador opaco y los datos se consulten server-side.
Buenas prácticas para JWT en APIs
- Verifica firma y limita algoritmos permitidos (evitar “alg=none”).
- Valida exp/nbf (no aceptar tokens expirados o “no válidos aún”).
- Rotación de claves y gestión de revocación si aplica.
- Payload pequeño: tokens enormes afectan cada request (latencia y ancho de banda).
- No confíes en claims sin validar firma.
- Usa HTTPS y cookies seguras si el token viaja en navegador.
Cuándo te conviene convertir entre Base64URL y Base64
A veces necesitas pasar un header/payload Base64URL a una librería que solo entiende Base64 estándar. En ese caso:
- Reemplaza
-por+ - Reemplaza
_por/ - Restaura padding
=hasta múltiplo de 4
En la práctica, es más fácil usar un conversor que soporte ambas variantes: Base64/Base64URL.
Base64URL más allá de JWT: usos frecuentes
- URLs firmadas y parámetros de tracking.
- Cookies (cuando necesitas formato seguro en HTTP).
- IDs opacos en enlaces (aunque recuerda: no es seguridad).
- Integraciones donde el texto debe sobrevivir a escapes y codificaciones.
FAQ
¿JWT usa Base64 o Base64URL?
Header y payload usan Base64URL.
¿Por qué puedo “leer” un JWT?
Porque no está cifrado, está codificado. La integridad se garantiza con la firma.
¿Cómo decodifico rápido un JWT?
Pega el header o payload en el conversor Base64URL y obtendrás el JSON.
¿Qué hago si falta padding?
Restaura = hasta que la longitud sea múltiplo de 4, o usa una herramienta que lo haga por ti.
¿Es mala idea meter datos sensibles en el payload?
Sí. Cualquiera puede decodificarlo. Para confidencialidad, usa cifrado (JWE) o un token opaco.
¿La firma del JWT también es Base64URL?
La tercera parte es una firma codificada, pero no se interpreta como JSON. Se usa para verificación.
Herramienta: Decodificar Base64URL (JWT) y convertir Base64/Base64URL.
Decodificar JWT para depurar problemas reales de login
En la práctica, decodificar JWT se usa muchísimo para depurar incidencias como:
- “El token expiró demasiado pronto” → revisas
expyiat. - “Funciona en staging pero no en producción” → revisas
issyaud. - “El usuario no tiene rol” → revisas los claims de roles/permisos.
En estos casos, lo más rápido es copiar el header o payload y decodificarlo con Base64URL en la herramienta.
Buenas prácticas de seguridad: lo que audita un backend serio
- Algoritmo permitido (whitelist). No aceptar algoritmos inesperados.
- Validación de firma con la clave correcta.
- Validar
exp,nbf,iatcon tolerancia de reloj (clock skew) controlada. - Validar
issyaudcuando aplica. - Rotación de claves (kid) y revocación si el negocio lo requiere.
¿Por qué Base64URL elimina el padding?
El padding = no aporta información (solo rellena). En URLs y tokens, eliminarlo simplifica y evita escapes. Pero algunas librerías antiguas lo exigen. Por eso, cuando un decode falla, suele ser por padding. Un conversor que restaure padding automáticamente te ahorra tiempo.
Mini-glosario de claims frecuentes
sub: identificador del sujeto/usuario.exp: expiración (epoch).iat: emitido en.nbf: no válido antes de.iss: emisor.aud: audiencia.jti: id único del token (útil para revocación).
Para inspeccionar rápidamente estos campos, decodifica el payload con Base64URL y verás el JSON.
JWT y “solo codificado”: cómo explicarlo al equipo (sin malentendidos)
Un clásico en equipos es escuchar: “si puedo leer el JWT, entonces cualquiera puede hackearlo”. La aclaración correcta es:
- Visibilidad: cualquiera puede decodificar header/payload porque es Base64URL.
- Integridad: nadie debería poder modificar claims sin romper la firma (si el backend valida bien).
- Confidencialidad: no existe en un JWT firmado (JWS). Para confidencialidad se usa cifrado (JWE) o un token opaco.
Por eso la recomendación práctica es: no pongas datos sensibles en el payload y valida firma/claims siempre.
Debug de JWT paso a paso (escenarios típicos)
Escenario A: “Token expirado”
Decodifica el payload y revisa exp. Si el backend usa reloj diferente, puedes ver desajustes. En sistemas distribuidos, se suele permitir un pequeño margen (clock skew), pero sin exagerar.
Escenario B: “Audience inválida”
Si tu API valida aud, un mismatch rompe el login. Al decodificar, compruebas rápidamente si el token fue emitido para otra aplicación/cliente.
Escenario C: “Issuer inválido”
Revisa iss. Esto pasa mucho cuando cambias dominios entre entornos (staging/producción) o migras proveedor de identidad.
Escenario D: “Rol faltante”
Busca claims como roles, scope o permissions. A veces el problema es que el proveedor no está emitiendo el claim, o que el backend lo está leyendo con un nombre distinto.
¿Debo decodificar también la firma?
La firma (tercera parte) es útil para ver su longitud, pero no se interpreta como JSON. Sirve para verificación criptográfica. Si tu objetivo es “entender” el token, normalmente te basta con header y payload.
Tips para guardar JWT en frontend
- Si lo guardas en localStorage, cuidado con XSS.
- Si lo guardas en cookies, usa
HttpOnly,SecureySameSitecuando aplique. - No metas el JWT en URLs si puedes evitarlo (queda en historial y referers).
Para inspeccionar tokens sin depender de herramientas externas, usa el decodificador Base64URL del portal.