RefreshTokenInterceptor class

A Dio interceptor that handles automatic JWT token refresh.

This interceptor supports two strategies for token refresh:

  • Preemptive refresh: Checks token expiry before each request and refreshes if expired, preventing 401 errors.
  • Response and retry: Waits for a 401 response, then refreshes the token and retries the failed request.

Uses QueuedInterceptorsWrapper to ensure token refresh requests are serialized, preventing multiple concurrent refresh requests when several API calls fail simultaneously.

Example usage:

dio.interceptors.add(
  RefreshTokenInterceptor(
    authHandler: authHandler,
    exceptionHandler: exceptionHandler,
    exceptionOptions: exceptionOptions,
    authOptions: AuthOptions(
      refreshTokenExecutionType: RefreshTokenStrategy.preemptivelyRefreshBeforeExpiry,
      refreshTokenEndpoint: '/auth/refresh',
      resolveJwt: (response) => response.data['access_token'],
      resolveRefreshToken: (response) => response.data['refresh_token'],
    ),
  ),
);
Inheritance

Constructors

RefreshTokenInterceptor({required AuthHandler authHandler, required ExceptionHandler exceptionHandler, required ExceptionOptions exceptionOptions, required AuthOptions authOptions})
Creates a new RefreshTokenInterceptor.

Properties

authHandler → AuthHandler
Handler for authentication operations (token storage, refresh execution).
final
authOptions → AuthOptions
Authentication configuration options.
final
exceptionHandler → ExceptionHandler
Handler for processing exceptions that occur during token refresh.
final
exceptionOptions → ExceptionOptions
Options for exception handling configuration.
final
hashCode → int
The hash code for this object.
no setterinherited
isPreemptivelyRefreshBeforeExpiry → bool
Whether the preemptive refresh strategy is active.
no setter
isResponseAndRetry → bool
Whether the response-and-retry strategy is active.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onError(DioException error, ErrorInterceptorHandler handler) → void
Handles 401 Unauthorized errors (response-and-retry strategy).
override
onRequest(RequestOptions options, RequestInterceptorHandler handler) → void
Intercepts outgoing requests to check for token expiry (preemptive strategy).
override
onResponse(Response response, ResponseInterceptorHandler handler) → void
Passes the response through without modification.
override
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited