Improve refresh token flow / logic

[yayidg22]

Goals

1. Separate the logic between login and refresh token
2. Improve the documentation for the JS Auth Token Refresh.
3. Improve the development experience

Non-Goals

No response

Background

I've worked on many projects where sessions are handled with credentials. The flow is as follows:

You log in with credentials, which returns a token and a refresh_token. The token is placed as Bearer ${token} in the Axios or Fetch headers.

When an unauthorized 401 is detected (intercepting the call with Axios interceptors), the refresh token is used to obtain a new token and a new refresh token (if the refresh token is still valid).

Problems:
The data cannot be changed without going through the signIn (NextAuth method), getSession, and useSession methods.

What arises from these problems:
There is no authjs documentation that indicates how to use the token to make calls to external APIs (the documentation treats absolutely everything as if it were a full-stack Nextjs application), leaving a huge gap in how to do this and there being no standard way to do it.

My current solution for signing my API to make calls to my backend with the session token (backend separate from my NextJS application) is to create a context and with this, add the interceptors to my Axios instance (client-side).

In the average documentation I see online, the token (to sign the API) and refresh_token are saved in localstorage. When intercepting a 401 to start the refreshToken flow, it uses the values ​​in localstorage. However, I don't like this solution due to the redundancy and possible inconsistencies in the source of the information (since it's information that AuthJS has saved).

Of course, you can give an example of a refresh token implementation, which is handled as follows:

callbacks: {
    async jwt({ token, user, account }) {
      if (user) {
        token.accessToken = user.accessToken;
        token.refreshToken = user.refreshToken;
        token.expiresAt = Date.now() + user.expiresIn * 1000;
      }

      if (Date.now() < token.expiresAt) return token;

      try {
        const res = await fetch("https://your-api.com/refresh", {
          method: "POST",
          body: JSON.stringify({ refreshToken: token.refreshToken }),
          headers: { "Content-Type": "application/json" },
        });

        const refreshed = await res.json();
        token.accessToken = refreshed.accessToken;
        token.expiresAt = Date.now() + refreshed.expiresIn * 1000;
        return token;
      } catch {
        return { ...token, error: "RefreshAccessTokenError" };
      }
    }

But what happens in cases where the backend needs to invalidate one or all tokens, or where the logic regarding the refresh token isn't on the website's part?

Proposal

I propose that we do the same thing as updating the tokens stored in authjs:

export const { handlers, signIn, signOut, auth,refreshToken /* <-- newMethod */ } = NextAuth({ 
providers: [...providers], 
callbacks: {
...callbacks,
async refreshToken: ({ token,account, user }) =>
{ 
/*different refreshTokens logic based in providers this is if credentials case */
const newTokens = await refreshTokenService(/* token.token or account.token */) 
token = newTokens 
return token
}
},
});

And improve the documentation to add these cases
https://authjs.dev/guides/refresh-token-rotation?framework=Next.js