How can I refresh JWT tokens automatically in Flutter using Dio interceptors?

[aiotronic-pe]

Body

I'm building a Flutter application that uses Dio for HTTP requests and JWT tokens for authentication.

When the access token expires, the server returns a 401 response. I want to automatically refresh the token using a refresh token and retry the original request.

However, I'm concerned about multiple requests triggering the refresh process at the same time.

What is the best way to implement a token refresh mechanism using Dio interceptors without creating multiple refresh calls?

Guidelines

• I have read and understood this category's guidelines before making this post.

[iamamits]

You can solve this problem by using a single refresh lock mechanism so that only one request refreshes the token while other requests wait.

The idea is:

1. When a request returns 401, check if a refresh process is already running.
2. If not running → start refreshing the token.
3. If already running → wait for the refresh to complete.
4. Retry the original request after the new token is obtained.

Example implementation using Dio interceptors:

class TokenInterceptor extends Interceptor {
  final Dio dio;
  bool isRefreshing = false;
  List<RequestOptions> pendingRequests = [];

  TokenInterceptor(this.dio);

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) async {
    if (err.response?.statusCode == 401) {

      if (!isRefreshing) {
        isRefreshing = true;

        try {
          final refreshResponse = await dio.post("/refresh-token");

          final newToken = refreshResponse.data["access_token"];

          dio.options.headers["Authorization"] = "Bearer $newToken";

          // retry pending requests
          for (var request in pendingRequests) {
            request.headers["Authorization"] = "Bearer $newToken";
            dio.fetch(request);
          }

          pendingRequests.clear();

        } catch (e) {
          return handler.reject(err);
        } finally {
          isRefreshing = false;
        }
      }

      pendingRequests.add(err.requestOptions);
      return;
    }

    return handler.next(err);
  }
}

If this helps please mark the answer as accepted ✔

[CTZDev]

A robust way to solve this problem is to combine a refresh lock mechanism with request queuing to ensure that only one refresh request is executed at a time.

The typical pattern works like this:

1. Intercept responses using a Dio interceptor.
2. When a request fails with a 401 status code, check if a refresh process is already running.
3. If a refresh is already running, store the pending request and wait for the refresh to complete.
4. If no refresh is running, start the refresh token request.
5. Once the new token is obtained, update the Authorization header and retry all pending requests.

A simplified example structure could look like this:

class AuthInterceptor extends Interceptor {
  final Dio dio;
  bool isRefreshing = false;
  List<RequestOptions> pendingRequests = [];

  AuthInterceptor(this.dio);

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) async {
    if (err.response?.statusCode == 401) {

      if (isRefreshing) {
        pendingRequests.add(err.requestOptions);
        return;
      }

      isRefreshing = true;

      try {
        final refreshResponse = await dio.post("/auth/refresh");
        final newToken = refreshResponse.data["access_token"];

        dio.options.headers["Authorization"] = "Bearer $newToken";

        for (final request in pendingRequests) {
          request.headers["Authorization"] = "Bearer $newToken";
          dio.fetch(request);
        }

        pendingRequests.clear();

      } catch (e) {
        return handler.reject(err);
      } finally {
        isRefreshing = false;
      }
    }

    return handler.next(err);
  }
}

Some additional best practices:

• Store tokens in a secure storage solution.
• Centralize authentication logic in a dedicated AuthService or TokenManager.
• Handle refresh token expiration by forcing logout if refresh fails.
• Avoid retry loops by marking retried requests.