Never Ask Users to Log In Again: Understanding Refresh Tokens in Flutter

If you’ve ever built an authentication system in Flutter, you’ve probably come across terms like Access Token and Refresh Token. At first, they can seem a little confusing.

Questions like:

• Why do we need two tokens?
• Why not just use one token forever?
• When should I use a refresh token?
• How does Flutter know when to refresh it?

If you’ve had these questions, you’re in the right place.

In this article, we’ll understand refresh tokens in simple language, see why they exist, learn how they work, and finally look at a practical Flutter implementation.

First, What Is a Token?

Before talking about refresh tokens, let’s quickly understand what a token is.

Imagine you’re checking into a hotel.

At the reception, you verify your identity and receive a room key.

Now, every time you want to enter your room, you don’t have to show your passport again — you simply use the room key.

Authentication works in a similar way.

1. User logs in with email and password.
2. Server verifies the credentials.
3. Server returns a token.
4. The app uses this token whenever it makes an API request.

Instead of sending your username and password every time, your Flutter app sends the token.

Example:

GET /profile

Authorization: Bearer eyJhbGciOiJIUzI1Ni...

The server checks the token and knows who the user is.

The Problem with Long-Lived Tokens

Now imagine that your room key never expires.

If someone steals it, they can enter your room anytime — even months later.

The same applies to authentication tokens.

If an attacker gets your access token, they can use your account until the token expires.

That’s why access tokens are usually short-lived.

Common expiry times:

• 15 minutes
• 30 minutes
• 1 hour

This improves security.

But it introduces another problem…

After 30 minutes, your user would suddenly be logged out.

That wouldn’t be a great user experience.

Enter Refresh Tokens

This is where refresh tokens come in.

When the user logs in, the server usually returns two tokens.

{
    accessToken: "...",
    refreshToken: "..."
}

Think of them like this:

Access Token

• Used for every API request
• Expires quickly
• Safe even if stolen because it doesn’t last long

Refresh Token

• Used only to get a new access token
• Lives much longer
• Never sent with normal API requests

A Simple Analogy

Think of it like visiting an amusement park.

• Your access token is your ride ticket.
• Your refresh token is the VIP pass that lets you collect a new ride ticket when yours expires.

You don’t show the VIP pass every time you enter a ride.

You only use it when you need a fresh ticket.

How Refresh Tokens Work

Let’s see the complete flow.

Step 1: User Logs In

Flutter App
      |
      | Email + Password
      |
      V
Server

The server verifies the credentials and returns:

Access Token
Refresh Token

Flutter stores both securely.

Step 2: API Calls

Whenever Flutter calls an API:

GET /profile

Authorization: Bearer access_token

Everything works normally until the access token expires.

Step 3: Token Expires

Eventually, the server responds with something like:

401 Unauthorized

This usually means:

“Your access token has expired.”

Step 4: Refresh the Token

Instead of asking the user to log in again, Flutter silently sends the refresh token.

POST /refresh

{
    "refreshToken": "abc123..."
}

The server checks whether the refresh token is still valid.

If everything is fine, it returns:

{
   "accessToken":"new_access_token"
}

Sometimes the server also issues a new refresh token for better security.

Step 5: Retry the Original Request

Flutter replaces the old access token with the new one and retries the failed request automatically.

The user never notices anything happened.

Everything feels seamless.

Visual Flow

User Logs In
      │
      ▼
Receive Access Token + Refresh Token
      │
      ▼
Call APIs Using Access Token
      │
      ▼
Access Token Expires
      │
      ▼
401 Unauthorized
      │
      ▼
Send Refresh Token
      │
      ▼
Receive New Access Token
      │
      ▼
Retry Original API
      │
      ▼
Continue Using the App

Where Should Flutter Store These Tokens?

One of the biggest mistakes developers make is storing tokens in plain text.

Instead, use secure storage.

Good choices include:

• flutter_secure_storage
• Keychain (iOS)
• EncryptedSharedPreferences (Android)

Example:

final storage = FlutterSecureStorage();

await storage.write(
  key: 'access_token',
  value: accessToken,
);
await storage.write(
  key: 'refresh_token',
  value: refreshToken,
);

Never hardcode tokens or store them in your source code.

Basic Refresh Token Example in Flutter

Let’s imagine your API returns a 401 Unauthorized.

You could handle it like this:

Future<Response> getProfile() async {
  final response = await api.get('/profile');

if (response.statusCode == 401) {
    await refreshAccessToken();
    return await api.get('/profile');
  }
  return response;
}

The refresh method might look like this:

Future<void> refreshAccessToken() async {

final refreshToken =
      await storage.read(key: 'refresh_token');
  final response = await api.post(
    '/refresh',
    data: {
      'refreshToken': refreshToken,
    },
  );
  await storage.write(
    key: 'access_token',
    value: response.data['accessToken'],
  );
}

In production apps, this logic is usually placed inside an HTTP interceptor (for example, using Dio) so every request is handled automatically. That way, you don't need to write refresh logic for each API call.

What Happens If the Refresh Token Also Expires?

Refresh tokens aren’t valid forever.

If the refresh token has expired or has been revoked by the server, the refresh request will fail.

At that point, the app should:

1. Clear all stored tokens.
2. Redirect the user to the login screen.
3. Ask them to authenticate again.

This ensures the app remains secure.

Best Practices

Here are a few tips when implementing refresh tokens:

• Keep access tokens short-lived (for example, 15–60 minutes).
• Store tokens securely using secure storage.
• Never send the refresh token with every API request.
• Refresh tokens only when the server indicates the access token is no longer valid (commonly with a 401 response).
• Consider rotating refresh tokens if your backend supports it.
• Use interceptors to automate token refresh instead of duplicating code.
• Always use HTTPS to protect tokens in transit.

Common Mistakes

❌ Storing tokens in SharedPreferences

❌ Refreshing the token before every request

❌ Sending the refresh token with every API

❌ Ignoring failed refresh requests

❌ Keeping access tokens valid for months

Final Thoughts

Refresh tokens play an important role in balancing security and user experience.

Without them, users would have to log in repeatedly whenever an access token expired. With them, your app can quietly obtain a new access token in the background and keep users signed in without interruption.

As a Flutter developer, you don’t need to refresh tokens manually for every API call. A cleaner approach is to centralize this logic using an HTTP interceptor, letting your networking layer handle expired tokens automatically.

Understanding how access tokens and refresh tokens work together is a fundamental skill for building secure, production-ready Flutter apps. Once you grasp the flow, implementing authentication becomes much easier and your users get a smoother, more reliable experience.

Thanks for reading :) Happy Coding