Skip to content
pubscout

dio_refresh

2.0.0, released 5 weeks ago by iamdipanshus.in

Dio interceptor for automatic token refresh and retry on API failures

$ flutter pub add dio_refresh
Source repository

What it does

Provides a Dio interceptor that intercepts failed requests, triggers a token refresh callback using a singleton token manager, and retries the original requests. It also proactively validates tokens before requests are sent.

AI-written summary of version 2.0.0, based on the package's README and metadata. Report an inaccuracy

Use it when

  • Your Flutter app uses Dio for HTTP requests and requires automatic OAuth token refreshing.
  • You need to handle concurrent 401/403 errors cleanly by sharing a single refresh lock.

Skip it when

  • You are not using the Dio HTTP client.
  • Your backend does not implement a token refresh endpoint.

Strengths

  • Automatic token refresh and request retrying on API failures
  • Handles concurrent failures with a shared refresh lock to avoid duplicate refresh calls
  • Supports custom token validation and header generation

Weaknesses

  • Tight coupling to the Dio HTTP client package
  • Uses a singleton TokenManager pattern which may limit multiple distinct auth sessions

Setup

Kind
Flutter widgets
Effort
Low
Code generation
No
Direct dependencies
3

Not documented

import 'package:dio/dio.dart';
import 'package:dio_refresh/dio_refresh.dart';

void main() {
  final dio = Dio();
  final tokenManager = TokenManager.instance;
  
  dio.interceptors.add(DioRefreshInterceptor(
    tokenManager: tokenManager,
    authHeader: (tokenStore) => {'Authorization': 'Bearer ${tokenStore.accessToken}'},
    shouldRefresh: (response) => response?.statusCode == 401,
    onRefresh: (dio, tokenStore) async {
      final response = await dio.post('/refresh', data: {'refresh_token': tokenStore.refreshToken});
      return TokenStore(accessToken: response.data['accessToken'], refreshToken: response.data['refreshToken']);
    },
  ));
}

Alternatives

Packages that do the same job and could replace dio_refresh.

  • http2

    An HTTP/2 implementation in Dart for low-level transport and pooled HTTP/2 requests.

  • dio_web_adapter

    Web and WASM HTTP client adapter for Dio.

  • http

    A composable, Future‑based library for making HTTP requests across platforms.

  • alice_dio

    Dio interceptor and network logger for Alice network inspector UI

Works with

Packages commonly used together with dio_refresh: ones it builds on, ones built on it, and its own family.