auth0/angular2-jwt: attaching JWTs to Angular HttpClient requests

The problem it solves is one narrow slice of client auth

Most Angular applications that talk to a protected API end up writing the same interceptor by hand: read a token out of storage, check the request URL against a whitelist, add an Authorization header, and leave everything else alone. The README describes exactly that scope. The library provides an HttpInterceptor which automatically attaches a JSON Web Token to HttpClient requests.

That is the whole job. The README is explicit that the library does not have any functionality for, or opinion about, implementing user authentication and retrieving JWTs to begin with. It tells you to authenticate users with a regular HTTP request and save the resulting JWT in local storage or a cookie. So the audience is a team that already has a login flow and a token in hand, and wants the header-attaching part to stop being copy-pasted across services. If you are looking for a login screen, a token refresh scheduler or a session store, this is not that project.

How the interceptor decides which requests get a token

The mechanism is configuration-driven rather than convention-driven. JwtModule.forRoot takes a config object with three keys the README uses: tokenGetter, allowedDomains and disallowedRoutes. tokenGetter is a function you supply that returns the token string, typically reading localStorage. allowedDomains is an array of hosts the interceptor is permitted to attach the token to. disallowedRoutes is an array of URLs that must never receive it.

That design pushes two decisions onto you. First, the token source is a function rather than a fixed storage location, which means the library never reads storage on its own and never assumes where you put the token. Second, the domain and route lists are allowlists, so a request to a host you forgot to list simply goes out without an Authorization header. That is the safe default, but it fails quietly: nothing in the README describes a warning or error when a request is skipped. If a call returns 401 and you expected a token, the first thing to check is whether the host appears in allowedDomains.

The package name still says angular2, which is a historical artefact of the repository rather than a statement about supported Angular versions. The README states the project only supports the actively supported versions of Angular as stated in the Angular documentation, and that other versions might be compatible but are not actively supported. The published package version is 5.2.0, released on 2023-10-31, while the repository's last push was on 2026-09-10.

Installing @auth0/angular-jwt and attaching your first token

Installation is a single package from npm or yarn. The README gives both commands:

npm install @auth0/angular-jwt

Then register the module in your NgModule imports. You must import HttpClientModule as well, and you must provide a tokenGetter function. The README's example reads the token from localStorage under the key access_token and restricts attachment to example.com:

import { JwtModule } from "@auth0/angular-jwt";
import { HttpClientModule } from "@angular/common/http";

export function tokenGetter() {
  return localStorage.getItem("access_token");
}

@NgModule({
  bootstrap: [AppComponent],
  imports: [
    HttpClientModule,
    JwtModule.forRoot({
      config: {
        tokenGetter: tokenGetter,
        allowedDomains: ["example.com"],
        disallowedRoutes: ["http://example.com/examplebadroute/"],
      },
    }),
  ],
})
export class AppModule {}

After that, any request sent through Angular's HttpClient gets the token attached as an Authorization header with no per-call code. The README's usage example is a plain GET:

import { HttpClient } from "@angular/common/http";

export class AppComponent {
  constructor(public http: HttpClient) {}

  ping() {
    this.http.get("http://example.com/api/things").subscribe(
      (data) => console.log(data),
      (err) => console.log(err)
    );
  }
}

If you bootstrap with bootstrapApplication instead of an NgModule, the README gives a different arrangement. The module goes in through importProvidersFrom, and provideHttpClient must be called with withInterceptorsFromDi so the DI-based interceptor is actually registered:

bootstrapApplication(AppComponent, {
    providers: [
        importProvidersFrom(
            JwtModule.forRoot({
                config: {
                    tokenGetter: tokenGetter,
                    allowedDomains: ["example.com"],
                    disallowedRoutes: ["http://example.com/examplebadroute/"],
                },
            }),
        ),
        provideHttpClient(
            withInterceptorsFromDi()
        ),
    ],
});

Forgetting withInterceptorsFromDi in a standalone app is the kind of mistake that produces no error and no header, which is why the README calls the difference out explicitly.

What the library deliberately leaves to you

The most consequential limitation is stated in the README rather than discovered in the code: there is no authentication implementation here at all. No login, no token retrieval, no refresh. A refresh-token flow, if you need one, is your code calling your own endpoint and updating whatever tokenGetter reads. The library will pick up the new value on the next request because the getter is invoked as a function, but nothing schedules that refresh, handles a 401 by retrying, or coordinates concurrent requests during a refresh.

Token storage is also your decision, and the README's own example uses localStorage. That is the convenient choice and it is exposed to any script running on the page, which is a trade-off the documentation does not discuss. The README simply notes that in most cases you will save the JWT in local storage or in a cookie, and moves on. Teams with strict requirements around XSS exposure should treat that as a decision to make deliberately, not a default to accept.

The versioning story is the other practical constraint. The latest published release is v5.2.0 from 2023-10-31, and the README ties support to whatever Angular currently lists as actively supported. Those two facts can diverge: a library release can be older than the Angular versions a reader is running. The README acknowledges this by saying other versions might be compatible but are not actively supported, which is honest and also means you are on your own if a future Angular release changes interceptor wiring.

Where a hand-written interceptor is the better call

The honest alternative is not another package. It is the interceptor you would write yourself in about twenty lines: a class implementing HttpInterceptor that clones the request, reads the token, and sets the Authorization header. If your rules are more than a domain allowlist and a route denylist, that hand-written version is easier to reason about than configuring someone else's. Conditional attachment based on route data, per-request opt-out flags, retry-on-401 with a refresh call, or attaching different tokens for different backends are all things you would end up expressing outside this library's config object anyway.

The case for taking the dependency is uniformity. When several teams share a codebase, a single configured interceptor with an explicit allowedDomains list is easier to audit than five hand-rolled versions with slightly different header logic. The library also ships its own tests, including a type test script in package.json, and the repository carries an API.md and an EXAMPLES.md, so the behaviour you are relying on is documented in more than one place. That matters more than the line count it saves.

Maintenance, licensing and the upgrade question

The repository is not archived, and its last push was on 2026-09-10, which is recent. That is separate from the release cadence: the newest published version is v5.2.0 from 2023-10-31, preceded by v5.1.2 on 2022-12-20 and v5.1.1 on 2022-12-15. Repository activity and npm releases are not the same signal, and anyone pinning a version should look at the release list rather than the commit history.

The project is MIT licensed, which permits commercial use and modification; the README points to the LICENSE file for the full text. That is a permissive licence with few obligations, but it is not legal advice and your own compliance review is the place to settle questions about attribution in distributed builds.

Upgrade cost is dominated by Angular, not by this package. Because the README supports only Angular's actively supported versions, an Angular major upgrade is the event that forces you to check whether a compatible release of this library exists. If the npm release list has not moved since 2023-10-31, that check is not something you can resolve by reading the changelog alone. The repository does carry a CHANGELOG.md, so the first step is to read it for the version you are moving to.

Editorial conclusion

Adopt it if you already have a working login flow and just need tokens attached to HttpClient calls, with allowedDomains and disallowedRoutes set explicitly. Do not adopt it expecting authentication, token storage or refresh logic: the README states the library has no opinion on retrieving JWTs. Before wiring it in, verify that your Angular version is one the Angular documentation still lists as supported, since the README supports only those, and confirm the interceptor does not attach a token to your login endpoint by listing that route in disallowedRoutes.

Frequently asked questions

Official sources

1. auth0/angular2-jwt on GitHub
2. Issues
3. License: MIT
4. README
5. Releases