jwt-decode

What is jwt-decode?

The jwt-decode npm package is a small browser library that helps decoding JWTs token which are Base64Url encoded. It is particularly useful for getting the payload or header information out of a JWT token without verifying its signature.

What are jwt-decode's main functionalities?

Decode JWT Token

This feature allows you to decode a JWT token to retrieve the payload and header information. The code sample shows how to use jwt-decode to decode a token and log the decoded payload to the console.

var jwtDecode = require('jwt-decode');
var token = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ';
var decoded = jwtDecode(token);
console.log(decoded);

Other packages similar to jwt-decode

jsonwebtoken

jsonwebtoken is a popular npm package that not only decodes JWT tokens but also verifies and signs them. It provides a full implementation of JSON Web Tokens, unlike jwt-decode which only decodes tokens without validation.

jws

jws is a JSON Web Signature implementation that allows you to sign, verify, and decode JWTs. It is more feature-rich compared to jwt-decode, which only decodes tokens.

jwt-simple

jwt-simple is another npm package that allows encoding and decoding JWT tokens. It is similar to jwt-decode but also offers the ability to encode tokens, which jwt-decode does not.

README

IMPORTANT: This library doesn't validate the token, any well-formed JWT can be decoded. You should validate the token in your server-side logic by using something like express-jwt, koa-jwt, Microsoft.AspNetCore.Authentication.JwtBearer, etc.

:books: Documentation - :rocket: Getting Started - :speech_balloon: Feedback

Documentation

• Docs site - explore our docs site and learn more about Auth0.

Getting started

Installation

Install with NPM or Yarn.

Run npm install jwt-decode or yarn add jwt-decode to install the library.

Usage

import jwt_decode from "jwt-decode";

var token = "eyJ0eXAiO.../// jwt token";
var decoded = jwt_decode(token);

console.log(decoded);

/* prints:
 * { 
 *   foo: "bar",
 *   exp: 1393286893,
 *   iat: 1393268893  
 * }
 */

// decode header by passing in options (useful for when you need `kid` to verify a JWT):
var decodedHeader = jwt_decode(token, { header: true });
console.log(decodedHeader);

/* prints:
 * { 
 *   typ: "JWT",
 *   alg: "HS256" 
 * }
 */

Note: A falsy or malformed token will throw an InvalidTokenError error; see below for more information on specific errors.

Errors

This library works with valid JSON web tokens. The basic format of these token is

[part1].[part2].[part3]

All parts are supposed to be valid base64 (url) encoded json. Depending on the { header: <option> } option it will decode part 1 (only if header: true is specified) or part 2 (default)

Not adhering to the format will result in a InvalidTokenError with one of the following messages:

• Invalid token specified: must be a string => the token passed was not a string, this library only works on strings.
• Invalid token specified: missing part # => this probably means you are missing a dot (.) in the token
• Invalid token specified: invalid base64 for part # => the part could not be base64 decoded (the message should contain the error the base64 decoder gave)
• Invalid token specified: invalid json for part # => the part was correctly base64 decoded, however, the decoded value was not valid JSON (the message should contain the error the JSON parser gave)

Use with typescript

The return type of the jwt_decode function is determined by the header property of the object passed as the second argument. If omitted (or set to false), it'll use JwtPayload, when true it will use JwtHeader. If needed, you can specify what the expected return type should be by passing a type argument to the jwt_decode function.

You can extend both JwtHeader and JwtPayload to include non-standard claims or properties.

import jwtDecode from "jwt-decode";

const token: string = "eyJhsw5c";
const decoded = jwtDecode<JwtPayload>(token); // Returns with the JwtPayload type

Use as a CommonJS package

const jwt_decode = require('jwt-decode');
...

Include with a script tag

Copy the file jwt-decode.js from the build/ folder to your project somewhere, then include it like so:

<script src="jwt-decode.js"></script>

Feedback

Contributing

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

• Auth0's general contribution guidelines
• Auth0's code of conduct guidelines

Raise an issue

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

---

Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0?

This project is licensed under the MIT license. See the LICENSE file for more info.

Changelog

Version 4.0.0-beta.0

Full Changelog

A new version of the library, including a couple of improvements:

• No longer include a polyfill for atob, as this is supported in all major browsers (and node environments > 14).
• Compile to ES2017, dropping support for anything that does not support ES2017 (which should be very limited according to caniuse)
• Use Node's atob when running on node.
• Drop support for Node 14, add support for Node 20.
• Add support for package.json's exports field, for better CJS/ESM support
• Reorganize build artifacts for better CJS/ESM support (cjs and esm needs to be their own directory with a cjs specific package.json file)
• Drop manual UMD bundle creation in index.standalone.ts, but rely on rollup instead.
• Infer JwtPayload and JwtHeader default types from the header argument by using overloads.

Additionally, this PR ensures the file size is decreased:

• ESM and CJS decreased by 22%
• UMD decreased by 37%

Even though some users might experience breaking changes, mostly because of the exports field, the majority should be able to update without making any changes, assuming the SDK is used in environments with support for atob.