Refresh Tokens

This guide covers two distinct concepts: provider refresh tokens (for calling external APIs) and session refresh tokens (for extending user sessions).

Provider Refresh Tokens

gau uses its own JWT for sessions and does not require OAuth refresh tokens to keep a user signed in. However, when you need to call a provider API (Google, Microsoft), gau can store provider access/refresh tokens and automatically refresh/rotate them for you.

What are provider refresh tokens?

Provider refresh tokens let your app get new access tokens without asking the user to sign in again. When you want to call a provider’s API (like querying Google Calendar or fetching Microsoft emails), you need an access token, but those expire quickly. The refresh token lets you get a fresh one behind the scenes.

How gau stores tokens

During the OAuth callback, gau saves provider tokens into the accounts table via your adapter:

accessToken, refreshToken, expiresAt, tokenType, scope, idToken (when available)
On subsequent sign-ins, these values are updated for already-linked accounts.

Automatic Refresh & Rotation

gau exposes a server-side helper to retrieve a valid provider access token, refreshing and rotating as needed:

const result = await auth.getAccessToken(userId, 'google')
if (!result)
  throw new Error('No access token available')

const { accessToken } = result
// Use accessToken to call Google APIs...

Behavior:

If the stored access token is still valid, it’s returned as-is.
If it’s expired and a refreshToken exists (and the provider supports it), gau calls the provider’s token endpoint.
If a new refresh token is returned, gau rotates it and persists the change via your adapter.