The barrier on the road - HTTP interceptors

You already know how to put the clan seal on a letter: you build an

HttpHeaders

set()

And the rule reads like this: every courier who leaves the walls carries a watch token with him - a token, in our language. Not only the one sent for the roll of samurai, but also the one with the recruit, the one with the promotion order, the one asking for a name to be struck off the register. Your clan registry has five methods, so five times you write out the same line with the

Authorization

With the shields from the lesson on failures it is exactly the same. An expired token looks identical in every method: status 401, and the user has to be sent back to the login screen. Copied into nine methods, the same error handling is the same work done nine times - and nine places where it can be broken.

On the Tokaido road nobody solved this by posting a scribe in every house. They built a barrier station: a post set across the road, which everyone travelling that way has to pass. One place and one custom - stamp the seal, write the crossing into the book, let the traveller through. In Angular that barrier is called an interceptor, and this lesson is about it, @name. It is what the lesson on request options was pointing at when it deliberately left the

Authorization

What the barrier is, and what it is not

A barrier is a function you never call yourself. Angular calls it, and at a very precise moment: the request has already been built by

HttpClient

Remember it in a single sentence, because it is the heart of the whole lesson: an interceptor exists to modify requests and responses globally, and the most common reason for putting one up is to add a token to every request.

It is worth fencing that off straight away from three things a barrier gets confused with. First, it is not a wall for blocking unwanted requests. The requests in your application are sent by your own code, so there is nothing to sift out, and an interceptor practically always ends by passing the request on. Refusing entry is the job of the route guards you posted at the gates in the module on routing, and of the server on the other side. Second, a barrier is not a mechanism for caching responses: the memory for data already fetched you built in the lesson on shields, inside the service, with a map and the

shareReplay

Content-Encoding

Do not mix the barrier up with a gate guard either. A route guard answered once per navigation and said "you may pass" or "turn back". The barrier stands on the road and travels with every single request, and its answer is not a verdict but traffic let through. What they have in common is that both are ordinary functions and both can reach for a service through

inject()

The shape of a barrier: HttpInterceptorFn

So that TypeScript knows what kind of function to expect here, the

@angular/common/http

HttpInterceptorFn

There are two parameters and you will use both in every barrier you ever write. The first, traditionally named

req

HttpRequest

next

Let us start with a barrier that stops nobody, so that you see the construction itself first, with no logic inside.

1// interceptors/audit.interceptor.ts
2import { HttpInterceptorFn } from '@angular/common/http';
3
4export const auditInterceptor: HttpInterceptorFn = (req, next) => {
5  return next(req);
6};

This barrier takes the request and gives it back untouched, and its resulting stream is exactly what

next

new

Learn the name of the type letter by letter, because three others sound just as sensible and each of them fails for a different reason. I checked all three with the TypeScript compiler on Angular 19. The name

InterceptorFunction

@angular/common/http

HttpHandler

handle()

HttpInterceptor

intercept()

withInterceptorsFromDi()

inject()

Standing the barrier on the road

The function alone will intercept nothing until you point out its place on the road. There is exactly one such place and you know it from the first waypoint in this module: the

provideHttpClient()

withInterceptors()

1// app.config.ts
2import { ApplicationConfig } from '@angular/core';
3import { provideHttpClient, withInterceptors } from '@angular/common/http';
4import { auditInterceptor } from './interceptors/audit.interceptor';
5
6export const appConfig: ApplicationConfig = {
7  providers: [
8    provideHttpClient(withInterceptors([auditInterceptor]))
9  ]
10};

Look at that one line token by token, because you will be reproducing it: first the name

provideHttpClient

withInterceptors

HttpClient

auditInterceptor

The most important part is what has not changed. The clan registry, the armoury and every other service look exactly as they did yesterday: not one new line, not one new import. The service does not know that a post has been set up on the road, and that is the whole strength of this solution. The components have not changed either, because they talk to the service and not to the network.

Two details in that array can hurt. There are no parentheses after the name

auditInterceptor

[auditInterceptor()]

withInterceptors

HttpInterceptorFn

A seal on every scroll

Time for the barrier to do some real work. Let us agree that the project contains an

AuthService

getToken()

null

inject()

@angular/core

Before you add the header, though, you have to learn the rule that governs everything here:

HttpRequest

req.headers = ...

req.url

Instead of scraping you therefore make a copy. The

clone()

HttpRequest

1// interceptors/auth.interceptor.ts
2import { HttpInterceptorFn } from '@angular/common/http';
3import { inject } from '@angular/core';
4import { AuthService } from '../services/auth.service';
5
6export const authInterceptor: HttpInterceptorFn = (req, next) => {
7  const authService = inject(AuthService);
8  const token = authService.getToken();
9
10  if (token) {
11    const authReq = req.clone({
12      headers: req.headers.set('Authorization', `Bearer ${token}`)
13    });
14    return next(authReq);
15  }
16
17  return next(req);
18};

I ran this barrier on a real Angular 19 HTTP chain against a stub server. What reached the server was a request with an

Authorization

Bearer

req

Authorization

next

clone()

Inside that copy a second immutability is at work, the one from the lesson on request options:

req.headers.set(...)

clone()

req.headers.set('Authorization', ...)

The barrier itself still stands nowhere until you register it - and the registration looks exactly as it did a moment ago, only with a different name in the array:

provideHttpClient(withInterceptors([authInterceptor]))

Let me disarm three misunderstandings about

clone()

clone()

clone()

withInterceptors

auditInterceptor

clone()

headers

When a service is needed for nothing but a single question, those first two lines may be folded into one. The result of

inject()

1const token = inject(AuthService).getToken();

This form means exactly the same as the previous two lines, and in practice it is the most common one - the

authService

inject()

next

What you can see on the way back

So far we have only been looking one way. But

next(req)

pipe()

So let us build a book of crossings: a barrier that measures how long the courier was on the road. For plain watching there is the

tap

type

HttpEventType

HttpEventType.Response

1// interceptors/logging.interceptor.ts
2import { HttpEventType, HttpInterceptorFn } from '@angular/common/http';
3import { tap } from 'rxjs';
4
5export const loggingInterceptor: HttpInterceptorFn = (req, next) => {
6  const started = Date.now();
7
8  return next(req).pipe(
9    tap(event => {
10      if (event.type === HttpEventType.Response) {
11        console.log(req.method, req.url, Date.now() - started, 'ms');
12      }
13    })
14  );
15};

Once this is running, one row appears in the console for every request: the method, the address and a number of milliseconds. I will not promise you any particular number, because it depends on the network and on the server - against a stub server on the same machine mine kept coming out as a single millisecond, and against a real castle across the mountains it will be hundreds. What matters more is what has not changed: the request went out exactly as it would without the barrier, the response came back to the component untouched, and

tap

One detail is surprising at the first meeting. I checked which events pass through the barrier during an ordinary

get()

Sent

Response

HttpEventType.Response

While we are at it, remember when a barrier speaks at all. I checked it with a counter: after the stream was built but before any subscription, the function had not run once; after the first subscription, once; after the second, twice. HTTP streams are lazy, so a barrier is crossed once per actual journey of a courier, and not once per application.

An expired token, or one error handled in one place

Since operators may be added on the way back, you can also lay error handling there - and there is one error that looks the same in every request in the whole application. Status 401 means "your token is not valid". Whatever you were doing, the ending is the same: clear the token and send the user back to the login screen.

You already know all the building blocks.

catchError

throwError

HttpErrorResponse

Router

navigate()

inject()

1// interceptors/error.interceptor.ts
2import { HttpErrorResponse, HttpInterceptorFn } from '@angular/common/http';
3import { inject } from '@angular/core';
4import { Router } from '@angular/router';
5import { catchError, throwError } from 'rxjs';
6import { AuthService } from '../services/auth.service';
7
8export const errorInterceptor: HttpInterceptorFn = (req, next) => {
9  const authService = inject(AuthService);
10  const router = inject(Router);
11
12  return next(req).pipe(
13    catchError((error: HttpErrorResponse) => {
14      if (error.status === 401) {
15        authService.logout();
16        router.navigate(['/login']);
17      }
18      return throwError(() => error);
19    })
20  );
21};

I ran this against a server answering with status 401. The result: the token was cleared, the router was ordered to go to

/login

throwError

Notice where both

inject()

pipe()

catchError

inject()

catchError

The retry from the lesson on shields has a place here just as good as

catchError

next(req)

The order of barriers on the road

Barriers on one road stand one after another, and the order of entries in the array is the order in which they are passed. Let us register all three at once.

1// app.config.ts
2import { ApplicationConfig } from '@angular/core';
3import { provideHttpClient, withInterceptors } from '@angular/common/http';
4import { authInterceptor } from './interceptors/auth.interceptor';
5import { loggingInterceptor } from './interceptors/logging.interceptor';
6import { errorInterceptor } from './interceptors/error.interceptor';
7
8export const appConfig: ApplicationConfig = {
9  providers: [
10    provideHttpClient(
11      withInterceptors([authInterceptor, loggingInterceptor, errorInterceptor])
12    )
13  ]
14};

I traced a passage through three such posts and the result is worth remembering: on the way out the courier passes them in the order they are written, that is auth, logging, error, and only then goes out into the network. On the way back he returns in the reverse order: error, logging, auth. That is natural, because each barrier wraps the stream of the previous one - the further into the array, the closer to the network.

The practical conclusion is that the barrier which adds the seal should stand earlier than the one that looks at the outcome. Then the timer measures the passage of an already sealed request, and the error handling sees the response to the very request that really left the walls. The reversed order will compile too and will even work, but you will start seeing in your book requests without the header you did after all glue on.

A barrier you are allowed to skip

There is one road, however, on which the seal is in the way. The motto carved over the gate may be read by anyone without a token, and sending the token where it is not needed is at best pointless chatter, at worst showing a clan secret to a stranger.

It is tempting to test the address inside the barrier, something along the lines of "if the address ends with motto, let it through without a seal". I advise against that, @name: a condition built on the text of an address breaks after every change of path, and nobody remembers it is there. The better way is for the caller to attach a note to the request, meant for the barrier.

HttpContext

HttpContextToken

1// interceptors/auth.context.ts
2import { HttpContextToken } from '@angular/common/http';
3
4export const SKIP_AUTH = new HttpContextToken<boolean>(() => false);

The angle brackets say that a boolean lies under this key, and the function

() => false

false

false

Now the barrier has to read that note. Every request has a

context

get()

1// interceptors/auth.interceptor.ts
2import { HttpInterceptorFn } from '@angular/common/http';
3import { inject } from '@angular/core';
4import { AuthService } from '../services/auth.service';
5import { SKIP_AUTH } from './auth.context';
6
7export const authInterceptor: HttpInterceptorFn = (req, next) => {
8  if (req.context.get(SKIP_AUTH)) {
9    return next(req);
10  }
11
12  const token = inject(AuthService).getToken();
13  if (!token) {
14    return next(req);
15  }
16
17  return next(req.clone({
18    headers: req.headers.set('Authorization', `Bearer ${token}`)
19  }));
20};

The only new thing here is the first pair of lines - the rest is the same seal as before, only written so that every case ends with a

return

if

inject()

That leaves the calling side, that is the one courier who is to walk past the barrier. You attach the note in the same options object in which you gave headers and

responseType

1// services/motto.service.ts
2import { HttpClient, HttpContext } from '@angular/common/http';
3import { Injectable, inject } from '@angular/core';
4import { SKIP_AUTH } from '../interceptors/auth.context';
5
6@Injectable({ providedIn: 'root' })
7export class MottoService {
8  private http = inject(HttpClient);
9
10  readMotto() {
11    return this.http.get('/api/motto', {
12      responseType: 'text',
13      context: new HttpContext().set(SKIP_AUTH, true)
14    });
15  }
16}

I sent two requests through this configuration at once. The ordinary one, for the roll of samurai, reached the server with an

Authorization

There is one difference from headers here that is easy to trip over.

HttpHeaders

set()

HttpContext

set()

new HttpContext().set(...)

Remember, @name: a barrier is one place on the road that every courier passes through - write the seal in there, and you will stop writing it everywhere else.