OAuth Provider Token Lifecycle#

When a user authenticates via an upstream OAuth/OIDC provider (Google, GitHub, etc.), Better Auth stores the provider-issued tokens in the account table, creates its own independent session, and exposes client-initiated endpoints for downstream token refresh. Better Auth's session lifetime is not coupled to the upstream provider's token expiry or revocation events — there is no built-in back-channel or front-channel logout integration.

Key source files:

Token Storage#

All upstream OAuth tokens are stored in the account table (one row per provider per user). The relevant fields 1:

All five token columns carry returned: false, which causes parseAccountOutput() to strip them from any API response — preventing accidental token exposure.

Optional encryption. When encryptOAuthTokens is enabled, tokens are encrypted at rest via setTokenUtil() before being written, and decrypted with decryptOAuthToken() before use.

When tokens are written:

• New user registration — user and account rows are created atomically in a transaction by createOAuthUser() 2
• Existing account sign-in — updateAccount() writes fresh tokens when account.updateAccountOnSignIn is not false 2
• Account linking — linkAccount() writes tokens for the newly linked provider account 2

Known quirk: If the upstream provider omits expires_in from its token response, accessTokenExpiresAt is undefined. Because the update object filters out undefined values before writing to the database, the expiry timestamp is silently left stale on re-sign-in 3.

Session Creation After OAuth Callback#

The /callback/:id endpoint handles responses from every social/OAuth provider 2. The simplified flow:

Provider redirect → /callback/:id
  1. Exchange code → tokens (validateAuthorizationCode)
  2. Fetch user profile (getUserInfo)
  3. handleOAuthUserInfo() → upsert user + account rows, store tokens
  4. internalAdapter.createSession(user.id) ← Better Auth session
  5. Set session cookie → redirect

The session created in step 4 is keyed only to user.id — it has no reference to the upstream access or refresh token 2. Its lifetime is governed by Better Auth's own session.expiresIn configuration, not by the upstream token's exp.

Redirect destination after callback 2:

• New user → newUserURL if configured, otherwise callbackURL
• Returning user → callbackURL

Explicit account linking (when the OAuth state carries a link flag) skips session creation entirely — the flow updates/creates the account row and redirects back without touching the session 2.

Client-Initiated Token Refresh#

Two endpoints in src/api/routes/account.ts expose on-demand refresh of upstream provider tokens. Neither runs automatically — the caller (client or server-side code) must invoke them explicitly.

GET /get-access-token#

Delegates to getValidAccessToken(). If the stored access token is still valid (not within 5 seconds of expiry), it is returned as-is. If expired, the endpoint decrypts the refresh token and calls provider.refreshAccessToken() before returning. Accepts providerId, optional accountId, optional userId in the request body. Returns: accessToken, accessTokenExpiresAt, scopes (as an array), idToken 4.

POST /refresh-token#

/refresh-token forces an unconditional refresh regardless of token expiry. It validates that the provider supports refresh, decrypts the stored refresh token, calls provider.refreshAccessToken(decryptedRefreshToken), persists the new tokens, and returns the full updated token set including refreshToken, refreshTokenExpiresAt, providerId, and accountId 5.

After every refresh#

Both paths call internalAdapter.updateAccount() to persist the new tokens 6. If storeAccountCookie is enabled, the account cookie is also updated via setAccountCookie() with a 5-minute TTL 7.

Error codes#

Session Decoupling from Upstream Provider Lifecycle#

Better Auth's session is architecturally independent of the upstream OAuth provider's token lifecycle. There is no built-in mechanism that invalidates a Better Auth session because the upstream provider's access or refresh token has expired or been revoked.

What is absent:

• No OIDC back-channel logout — upstream providers cannot push a logout signal to Better Auth. (The oauth-provider plugin, when Better Auth acts as the authorization server, has its own session-delete hook that revokes session-bound tokens — but that is a different concern from upstream-provider-initiated logout 8.)
• No front-channel logout — no endpoint listens for OIDC logout_token or session-iframe messages from upstream providers.
• No periodic/automatic token refresh — upstream token validity is checked only when /get-access-token or /refresh-token is explicitly called. A revoked upstream refresh token is not detected until the next explicit call.

Practical consequence: A user who revokes Better Auth's access at the upstream provider (e.g., removes the app from their Google account) retains a fully valid Better Auth session until that session's own expiry. The account row still holds a stale (now-invalid) refresh token.

Workaround (custom implementation): On each sensitive request, call auth.api.getAccessToken({ providerId }). If the call returns FAILED_TO_REFRESH_ACCESS_TOKEN (refresh token revoked by provider), explicitly revoke the Better Auth session. Setting session.expiresIn to match the upstream refresh token lifetime provides a hard upper bound, but does not react to revocation.

Open issues tracking this gap:

• #10386 — Revoke oauth-provider tokens when user removes consent 8
• #10418 — accessTokenExpiresAt not updated when upstream omits expires_in 3
• #10267 — validateJwtAccessToken returns active: true for JWTs with expired Better Auth sessions 9