In Angular, how do you write an HttpInterceptorFn that attaches a bearer token to API requests, and why must it clone the request?

## What an interceptor is An **interceptor** in Angular's `HttpClient` is middleware: code that runs for every request made through `HttpClient`, between your service call and the **backend** that actually talks to the network. Since standalone APIs became the norm, the recommended form is a plain function of type **`HttpInterceptorFn`**: ```ts type HttpInterceptorFn = (req: HttpRequest<unknown>, next: HttpHandlerFn) => Observable<HttpEvent<unknown>>; ``` - `req` is the outgoing **`HttpRequest`**: method, URL, headers, params, body, context. - `next` is an **`HttpHandlerFn`** that passes a request to the next interceptor, or to the backend when this is the last one. - The return value is the Observable of `HttpEvent`s the rest of the chain produces, which the interceptor may also transform. ## Why the request must be cloned `HttpRequest` is **immutable**. Its fields are `readonly`, and its `headers` and `params` are the immutable `HttpHeaders` and `HttpParams` types, whose `set()` returns a new instance. Two consequences: 1. Writing `req.headers.set('Authorization', value)` and then `return next(req)` sends the request *without* the header — `set()` built a new `HttpHeaders` that was thrown away. 2. The only way to change a request is `req.clone(update)`, which returns a new `HttpRequest` with the listed fields replaced. `clone()` accepts the ordinary request options plus conveniences: **`setHeaders`** sets (replaces) each listed header, **`setParams`** sets each listed query parameter, and `url`, `method` and `body` replace those fields. The Angular guide explains why the design is immutable: an interceptor can be handed the same request more than once — for example when a request is retried — and immutability keeps that repeatable. ## Writing the bearer-token interceptor ```ts export const authInterceptor: HttpInterceptorFn = (req, next) => { const token = inject(AuthService).accessToken(); if (!token || !req.url.startsWith('/api/')) { return next(req); } return next(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } })); }; ``` Step by step: 1. **`inject(AuthService)`** works because Angular calls each functional interceptor inside `runInInjectionContext` for the injector that configured it. The call must happen synchronously in the function body, not later inside an RxJS callback. 2. **Guard the destination.** An app also calls third-party APIs, analytics endpoints and CDNs through `HttpClient`; sending your access token to them leaks a credential. Match your own origin or path prefix explicitly. 3. **Skip when there is no token**, so anonymous calls go through unchanged. 4. **Clone once and forward** the copy with `next()`. ## Registering it The function does nothing until it is part of the `HttpClient` configuration: ```ts export const appConfig: ApplicationConfig = { providers: [provideHttpClient(withInterceptors([authInterceptor]))], }; ``` The array order is the chain order: the first interceptor sees the request first. ## Functional versus class-based interceptors | | `HttpInterceptorFn` | Class implementing `HttpInterceptor` | |---|---|---| | Shape | A function `(req, next)` | An `@Injectable` class with `intercept(req, next: HttpHandler)` | | Forwarding | `next(req)` | `next.handle(req)` | | Dependencies | `inject()` in the body | Constructor injection or `inject()` in fields | | Registration | `withInterceptors([...])` | `HTTP_INTERCEPTORS` multi-provider plus `withInterceptorsFromDi()` | | Guide's recommendation | Preferred | Supported, order harder to predict | Class-based interceptors are still in many codebases; the logic inside them is the same. ## Reading the token at the right moment The token should be read **per request**, inside the interceptor, from a service that always holds the current value — a signal or a plain field on an auth service. Capturing it in a module-level constant, or in a closure created once at start-up, freezes the first token forever, and a later refresh or login never reaches outgoing requests. The same applies to other per-user headers such as a tenant or locale header: compute them when the request passes through, not when the interceptor is defined. ## Common mistakes - Calling `req.headers.set(...)` and forwarding the original `req`. - Attaching the token to every URL, including other origins. - Calling `inject()` inside `pipe(catchError(...))` instead of at the top of the function. - Forgetting to register the function, so it never runs. - Reading the token once at module load time instead of per request, so a refreshed token is never picked up.