Quick answer: A generated auth interceptor sits between the client methods and the HTTP layer, attaches the current access token to every outgoing request, and handles a 401 by refreshing the token and retrying the original request once. The generator gives you the interceptor hook and the place to read and store tokens, but the refresh flow, secure storage, and coordination across concurrent calls are usually yours to configure. Keeping auth in one interceptor means every operation authenticates the same way instead of each call site adding headers by hand.
What the interceptor attaches
Before a request is sent, the interceptor reads the current token from a token store and adds it to the Authorization header, typically as a bearer scheme. API keys and other schemes follow the same pattern of injecting at one boundary. The interceptor also has to distinguish a missing token from an expired one: with no token, the client should obtain one or ask the user to sign in first, rather than sending an unauthenticated request it knows will fail.
Refreshing on a 401
When a protected call returns 401, the interceptor calls the refresh endpoint with the refresh token, stores the new access token, and replays the original request with it. That retry should happen once, not in a loop. If the refresh itself is rejected because the refresh token is expired or revoked, the client clears its stored tokens and asks the user to sign in again, since retrying cannot recover that state.
One refresh for many requests
Several requests can be in flight when the token expires, and letting each one refresh independently is a real failure mode, especially when the authorization server rotates refresh tokens and invalidates the old one. Concurrent 401s should share a single in-flight refresh: the first call starts it, and the others wait for the same result, then all retry with the new token.
| Situation | Correct behavior |
|---|---|
| No token | Sign in before sending |
| One 401 | Refresh, then retry once |
| Many concurrent 401s | Share one refresh |
| Refresh rejected | Clear storage, ask to sign in |
Verifying the flow
A configured interceptor still needs proof. Point the client at a local mock that returns 401 on the first protected call and 200 after refresh, then run an ordered scenario and assert the final status while checking the recorded requests; Powerduck can drive that scenario and confirm the refresh call happened before the retry, and that parallel calls did not trigger more than one refresh.
Access and refresh tokens play different roles
The two tokens are built for different jobs, and treating them the same hides why the flow works. An access token is short-lived and travels with every business request, so a leaked one has a narrow window in which it can be misused. A refresh token lives longer and is sent only to the authorization server, never to the business API, which keeps it out of the ordinary request path. Because it can mint new access tokens, a leaked refresh token is the more serious loss and is the one that most needs secure storage and rotation. That split is why the interceptor swaps the access token often while guarding the refresh token more tightly.
Honest limits
The generator does not know your authorization server's endpoint or rotation policy, so those details have to be configured rather than assumed. It also does not secure the token for you: tokens belong in a keychain or secure store, never in logs, and the client cannot by itself stop a token from leaking elsewhere. Replaying a failed request after refresh carries the same uncertainty as any retry for a non-idempotent call, since the server may have processed the first attempt.
Frequently asked questions
Where should the token be stored? In a keychain or secure store, not in logs or plain config files.
How many times should a 401 be retried? Once, after a successful refresh; a failed refresh should prompt sign-in.
What if several calls hit 401 at once? They should share one in-flight refresh and then all retry.
Does the generator handle my auth server? It provides the hook, but the endpoint and rotation policy are your configuration.
The bottom line
An auth interceptor centralizes token injection and turns a 401 into a refresh followed by a single retry, while concurrent calls share one refresh and failed refresh routes the user back to sign-in. Verify the sequence against a mock and keep tokens in secure storage. For more on generated clients, see the OpenAPI codegen guide hub.
Top comments (0)