OAuth token storage is an architecture decision, not a small implementation detail. This guide explains where access and refresh tokens generally belong in browser applications, mobile apps, and backend services; how to choose a pattern for public and confidential clients; and which storage, rotation, logging, and revocation controls to review as your system changes.
Overview
OAuth tokens allow an application to call an API on a user’s behalf, so the place that stores them becomes part of the application’s attack surface. A stolen token may be usable without the user’s password, and a refresh token can potentially create new access tokens for longer than a single access-token lifetime. The right design therefore depends on the client type, the operating environment, the sensitivity of the APIs, and whether your application has a trusted backend.
Start by separating two questions: where should the application keep a token while it is needed, and where should it persist a token between sessions? Keeping a short-lived access token in process memory is different from writing it to browser storage or a device credential store. Reducing persistence can limit exposure, but it may also affect user experience and recovery after an application restart.
As a general rule, avoid exposing long-lived credentials to environments that do not provide a trustworthy secret boundary. A browser application cannot keep a client secret confidential because its code and requests are delivered to the user’s device. A backend service, by contrast, can usually protect credentials using server-side access controls and a secrets-management system. Treat this distinction as a starting point rather than a substitute for a threat model.
| Client or environment | Common safer pattern | Primary concerns to review |
|---|---|---|
| Browser application with a backend | Keep tokens on the server and use a secure, server-managed session cookie in the browser. | CSRF protection, session fixation, cookie settings, session expiration, and backend access controls. |
| Browser-only application | Use authorization code flow with PKCE and minimize token persistence; prefer in-memory handling where practical. | Cross-site scripting, malicious dependencies, browser extensions, redirects, and user experience after reloads. |
| Mobile application | Use the platform’s protected credential facilities for refresh-token persistence and keep access tokens short-lived. | Device compromise, backup behavior, app-to-app interception, logout, revocation, and secure deep links. |
| Backend or server-to-server service | Store client credentials and tokens in a managed secret store or protected server-side configuration. | Least privilege, workload identity, secret access logs, rotation, isolation, and accidental disclosure. |
For configuration details such as redirect URIs, PKCE, scopes, claims, and session controls, use the OIDC configuration checklist alongside this storage review.
What to track
Browser applications
For a browser application with a trusted backend, a backend-for-frontend pattern is often easier to control. The server completes or assists with the OAuth exchange, stores or manages tokens away from browser JavaScript, and gives the browser an application session. A cookie used for that session should be reviewed for Secure, an appropriate SameSite setting, and HttpOnly where JavaScript does not need to read it. Cookie flags do not remove the need for CSRF defenses, careful session expiration, and output encoding.
In a browser-only client, do not treat localStorage as a secure vault. Any script running in the page’s origin may be able to read values stored there. That makes cross-site scripting, unsafe third-party scripts, and vulnerable dependencies especially important. If tokens must be handled in the browser, keep access tokens short-lived and consider in-memory storage to reduce persistence. Use authorization code flow with PKCE, validate the issuer and redirect behavior, and avoid placing tokens in URLs.
Track whether a framework or authentication library has changed its recommended browser pattern. A migration from one router, bundler, or state-management library to another can change how tokens are cached, serialized, or exposed to client code.
Mobile applications
Mobile applications should use the operating system’s protected credential mechanisms rather than ordinary preferences, an unencrypted local database, or a file that is readable by the application’s general storage layer. The exact API differs by platform, but the design questions are consistent: can another application read the value, does the value survive backup or device migration, and what happens after the user removes the app or changes device security settings?
Keep refresh tokens protected and limit the lifetime and scope of access tokens. Review the authorization redirect mechanism, including claimed HTTPS links or equivalent platform controls, so another application cannot easily intercept the response. Plan for logout, account switching, device loss, and refresh-token reuse signals. Mobile storage reduces ordinary exposure; it does not make a token safe on a rooted, jailbroken, or otherwise compromised device.
Backends and service workloads
Backend services should not place secrets in source code, container images, public configuration, or ordinary application logs. Use a secrets manager or an equivalent protected configuration system, restrict access by workload identity or service role, and separate credentials by environment and service where practical.
Track which service can request which token, which scopes it receives, and whether it really needs a refresh token. For machine-to-machine access, a short-lived workload credential or platform identity may be preferable to a manually copied long-lived secret, depending on the infrastructure. Log access to secrets and token endpoints without logging token values themselves.
Token lifecycle controls
Regardless of platform, maintain an inventory of access and refresh tokens: issuer, audience, scopes, client, environment, expected lifetime, and revocation path. Rotate refresh tokens when the authorization server and client design support it, detect unexpected reuse where possible, and provide an administrative or user-facing revocation route. Keep scopes narrow and request only what the feature needs.
When debugging a token, inspect claims such as issuer, audience, expiry, and scope without pasting a live credential into a third-party service. A JWT decoder can help with safe, local inspection, but decoding is not signature verification and a readable payload does not prove that a token is authentic. The JWT decoder and debugging guide covers this distinction in more detail.
Cadence and checkpoints
Make token storage a recurring review item rather than a one-time launch decision. A monthly or quarterly checkpoint is appropriate for many teams, with an additional review after a security incident, authentication-provider change, major framework release, or new client launch.
- Monthly: review authentication errors, refresh failures, unusual token-use patterns, scope changes, and logs for accidental credential exposure.
- Quarterly: confirm storage locations, cookie attributes, mobile credential APIs, secret-store permissions, token lifetimes, revocation procedures, and dependency versions.
- At each release: check whether new features require broader scopes, longer sessions, additional redirects, or a new client type.
- After an incident: rotate affected credentials, revoke sessions or refresh tokens as appropriate, preserve relevant evidence without retaining token values, and document the change.
Keep a short decision record for each client. Record whether it is public or confidential, whether it has a backend, where each token class is stored, what protects the session, and who owns revocation. This makes architecture reviews and framework migrations less dependent on individual memory.
How to interpret changes
A rise in refresh failures does not automatically mean the storage location is wrong. It may indicate expired consent, clock skew, revoked sessions, provider policy changes, a broken redirect, or a rotation implementation that is retrying an old refresh token. Investigate the complete lifecycle before changing storage.
Repeated access-token exposure in browser telemetry, support reports, or security testing is more serious. Check for tokens in URLs, error messages, analytics payloads, client-side state snapshots, source maps, and logs. Remove the exposure, invalidate affected credentials, and review whether a backend-for-frontend design would reduce the browser’s access to tokens.
Frequent mobile reauthentication may reflect an overly aggressive in-memory policy, but storing a refresh token in general-purpose device storage is not a safe fix. First verify the protected storage integration, backup settings, device clock, refresh handling, and user-session requirements.
Scope growth is an architectural signal. If a feature gradually requests broad API access, split clients or scopes where appropriate and reassess whether the token has become too valuable for its current environment. If a backend needs credentials for many unrelated functions, separate service identities can make revocation and auditing clearer.
When to revisit
Revisit this guide and your implementation whenever you add a browser, mobile, desktop, command-line, or server-to-server client; move from a browser-only design to a backend-assisted design; change identity providers; adopt a new authentication library; or introduce passkeys, delegated access, or new sensitive APIs. Also review the design when a framework changes its default cookie, storage, redirect, or session behavior.
Use this practical checklist during the next architecture review:
- List every client and classify it as public or confidential.
- Map access tokens, refresh tokens, client credentials, and application sessions separately.
- Write down the exact storage location and the code paths that can read each value.
- Remove tokens from URLs, logs, analytics, crash reports, and client-side error messages.
- Confirm PKCE and redirect validation for applicable authorization-code clients.
- Check cookie flags, CSRF defenses, session expiration, logout, and session fixation controls.
- Confirm that mobile credentials use protected platform storage and that backup behavior is understood.
- Review backend secret-store permissions, rotation ownership, scopes, and workload isolation.
- Test revocation, refresh-token rotation, account switching, device loss, and credential compromise scenarios.
- Record the review date, the next checkpoint, and the event that would trigger an earlier review.
Token storage is safest when it is treated as part of the identity system’s ongoing operations. Rechecking the decision as clients, dependencies, and APIs change helps keep a secure online identity architecture aligned with how the product actually works.
