Access tokens vs refresh tokens

These two tokenWhat is token?The smallest unit of text an LLM processes - roughly three-quarters of a word. API pricing is based on how many tokens you use. Ask AI for more types serve different purposes and have very different security requirements:

An access token is like a day-pass wristband at a concert, it works for the day, then it is worthless. A refresh tokenWhat is refresh token?A long-lived credential used solely to obtain new short-lived access tokens without requiring the user to log in again. Ask AI for more is like the receipt you can exchange for a new wristband, you need to keep it safe.

TokenWhat is token?The smallest unit of text an LLM processes - roughly three-quarters of a word. API pricing is based on how many tokens you use. Ask AI for more storage security

The most common mistake developers make is storing tokens in localStorage. It is convenient, it survives page refreshes, and every OAuthWhat is oauth?An authorization protocol that lets users grant a third-party app limited access to their account on another service without sharing their password. Ask AI for more tutorial shows it. It is also a serious security hole because any JavaScript on your page, including injected XSSWhat is xss?Cross-Site Scripting - an attack where malicious JavaScript is injected into a web page and runs in other users' browsers, stealing data or hijacking sessions. Ask AI for more scripts, can read it.

// Never do this - localStorage is readable by any script on the page
localStorage.setItem('access_token', token);
localStorage.setItem('refresh_token', token);

// Never return tokens raw to the client
res.json({ accessToken, refreshToken });  // Wrong!

Instead, keep tokens on the server and use an opaque sessionWhat is session?A server-side record that tracks a logged-in user. The browser holds only a session ID in a cookie, and the server looks up the full data on each request. Ask AI for more cookieWhat is cookie?A small piece of data the browser stores and automatically sends with every request to the matching server, often used for sessions. Ask AI for more to identify the user:

// Server-side: store the refresh token encrypted in your database
await db.updateUser(userId, {
  oauth_refresh_token: encrypt(refreshToken),
  token_expires_at: new Date(Date.now() + expiresIn * 1000)
});

// Set an httpOnly session cookie - JavaScript cannot read this
res.cookie('session', sessionId, {
  httpOnly: true,      // Not accessible via JavaScript
  secure: true,        // HTTPS only
  sameSite: 'strict',  // CSRF protection
  maxAge: 3600000      // 1 hour
});

Refreshing access tokens

When an access tokenWhat is token?The smallest unit of text an LLM processes - roughly three-quarters of a word. API pricing is based on how many tokens you use. Ask AI for more expires, you use the refresh tokenWhat is refresh token?A long-lived credential used solely to obtain new short-lived access tokens without requiring the user to log in again. Ask AI for more to get a new one without asking the user to log in again. Here is a complete refresh function:

async function refreshAccessToken(userId) {
  const user = await db.getUser(userId);
  const refreshToken = decrypt(user.oauth_refresh_token);

  const response = await fetch('https://oauth2.googleapis.com/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      refresh_token: refreshToken,
      client_id: process.env.GOOGLE_CLIENT_ID,
      client_secret: process.env.GOOGLE_CLIENT_SECRET,
      grant_type: 'refresh_token'
    })
  });

  if (!response.ok) {
    if (response.status === 400) {
      // The refresh token has been revoked or expired
      throw new Error('REFRESH_TOKEN_INVALID');
    }
    throw new Error('Token refresh failed');
  }

  const tokens = await response.json();

  // Google sometimes returns a new refresh token (token rotation)
  if (tokens.refresh_token) {
    await db.updateUser(userId, {
      oauth_refresh_token: encrypt(tokens.refresh_token)
    });
  }

  // Always update the expiration timestamp
  await db.updateUser(userId, {
    access_token_expires_at: new Date(Date.now() + tokens.expires_in * 1000)
  });

  return tokens.access_token;
}

Silent refresh middlewareWhat is middleware?A function that runs between receiving a request and sending a response. It can check authentication, log data, or modify the request before your main code sees it. Ask AI for more

You want users to stay logged in seamlessly. The trick is to refresh tokens proactively, before they expire, rather than reactively after a failed APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. Ask AI for more call. A middleware function that runs on every request is a clean place to do this:

async function tokenRefreshMiddleware(req, res, next) {
  const userId = req.session.userId;
  if (!userId) return next();  // Not logged in, skip

  const user = await db.getUser(userId);
  const expiresAt = user.access_token_expires_at;
  const fiveMinutes = 5 * 60 * 1000;

  // Refresh if the token will expire within 5 minutes
  if (expiresAt && Date.now() > expiresAt - fiveMinutes) {
    try {
      await refreshAccessToken(userId);
    } catch (error) {
      if (error.message === 'REFRESH_TOKEN_INVALID') {
        // Token revoked - clear session and ask user to log in again
        req.session.destroy();
        return res.status(401).json({ error: 'Session expired' });
      }
    }
  }

  next();
}

// Apply to all protected routes
app.use('/api', tokenRefreshMiddleware);

The 5-minute buffer handles the case where a tokenWhat is token?The smallest unit of text an LLM processes - roughly three-quarters of a word. API pricing is based on how many tokens you use. Ask AI for more expires during a slow API call. Without it, you might start a request with a valid token that expires before the response arrives.

TokenWhat is token?The smallest unit of text an LLM processes - roughly three-quarters of a word. API pricing is based on how many tokens you use. Ask AI for more rotation

Some providers (and you can implement this yourself too) use token rotation: every time you exchange a refresh tokenWhat is refresh token?A long-lived credential used solely to obtain new short-lived access tokens without requiring the user to log in again. Ask AI for more, the old one is immediately invalidated and a new one is issued. This limits the damage if an old refresh token leaks, an attacker cannot use it because it has already been replaced.

If your database still has the old refresh token when a new one arrives, something is wrong. You can detect token reuse attacks this way:

async function storeRotatedRefreshToken(userId, newRefreshToken, oldRefreshToken) {
  const user = await db.getUser(userId);
  const storedToken = decrypt(user.oauth_refresh_token);

  if (storedToken !== oldRefreshToken) {
    // Token reuse detected - someone may have used a stolen refresh token
    // Clear all tokens for this user and force re-authentication
    await db.clearTokens(userId);
    throw new Error('TOKEN_REUSE_DETECTED');
  }

  await db.updateUser(userId, {
    oauth_refresh_token: encrypt(newRefreshToken)
  });
}

TokenWhat is token?The smallest unit of text an LLM processes - roughly three-quarters of a word. API pricing is based on how many tokens you use. Ask AI for more revocation

When a user logs out, you should do three things: revoke the refresh tokenWhat is refresh token?A long-lived credential used solely to obtain new short-lived access tokens without requiring the user to log in again. Ask AI for more with the providerWhat is provider?A wrapper component that makes data available to all components nested inside it without passing props manually. Ask AI for more so it cannot be used again, clear it from your database, and destroy the sessionWhat is session?A server-side record that tracks a logged-in user. The browser holds only a session ID in a cookie, and the server looks up the full data on each request. Ask AI for more.

async function revokeToken(token) {
  // Google's revocation endpoint
  await fetch('https://oauth2.googleapis.com/revoke', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({ token })
  });
}

app.post('/logout', async (req, res) => {
  const userId = req.session.userId;

  if (userId) {
    const user = await db.getUser(userId);

    if (user.oauth_refresh_token) {
      try {
        await revokeToken(decrypt(user.oauth_refresh_token));
      } catch (e) {
        // Log but do not block logout if revocation fails
        console.error('Failed to revoke token:', e);
      }
    }

    // Always clear from the database regardless of revocation outcome
    await db.updateUser(userId, {
      oauth_refresh_token: null,
      access_token_expires_at: null
    });
  }

  req.session.destroy();
  res.clearCookie('session');
  res.json({ success: true });
});

Making authenticated APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. Ask AI for more calls

When you need to call a providerWhat is provider?A wrapper component that makes data available to all components nested inside it without passing props manually. Ask AI for more API (like GitHub's API to list a user's repositories), wrap the fetch call in a helper that handles tokenWhat is token?The smallest unit of text an LLM processes - roughly three-quarters of a word. API pricing is based on how many tokens you use. Ask AI for more refresh transparently:

class OAuthApiClient {
  constructor(userId) {
    this.userId = userId;
  }

  async request(url, options = {}) {
    const user = await db.getUser(this.userId);

    // Refresh proactively if token expires within 60 seconds
    if (Date.now() > user.access_token_expires_at - 60000) {
      await refreshAccessToken(this.userId);
    }

    const freshUser = await db.getUser(this.userId);
    const accessToken = decrypt(freshUser.oauth_access_token);

    const response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        Authorization: `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    });

    // 401 means the token was rejected - try one refresh and retry
    if (response.status === 401) {
      const newToken = await refreshAccessToken(this.userId);
      return fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          Authorization: `Bearer ${newToken}`
        }
      });
    }

    return response;
  }
}

// Usage
const client = new OAuthApiClient(userId);
const response = await client.request('https://api.github.com/user/repos');

Quick reference