Skip to main content

Authentication and Session Management

Authentication is one of the most failure-prone parts of a mobile product because it combines network behavior, secure storage, UX friction, compliance, and backend contract correctness. Treat it as a platform concern, not a screen flow.

Core decisions​

Teams should write down:

  • which identity provider or auth model is used
  • whether login is password, passkey, OTP, SSO, social, or enterprise federation
  • how tokens are stored
  • how refresh works
  • when re-authentication is required
  • how logout and revocation behave

If these answers vary across features, the app will behave unpredictably.

A reliable auth subsystem usually includes:

  • an auth service responsible for sign-in, token refresh, logout, and session inspection
  • secure storage abstraction owned by the app
  • one source of truth for current session state
  • navigation guards derived from auth state, not duplicated per screen
  • explicit support for session-expired and re-auth-required states

Do not spread token refresh logic across API hooks, screens, and interceptors independently.

Token lifecycle​

Document the lifecycle end to end:

  • initial credential exchange
  • token storage
  • access-token expiry
  • refresh-token use
  • server-side revocation
  • device logout
  • forced re-auth after suspicious activity

The client should assume tokens can expire, become invalid, or be revoked at any time.

UX expectations​

The auth system should define what users see when:

  • startup occurs with a valid session
  • startup occurs with an expired session
  • refresh fails due to network issues
  • a second factor is required
  • the account is locked or challenged
  • the app is opened from a deep link that requires auth

The most common mistake is treating auth as a binary logged-in or logged-out state. Real products need richer intermediate states.

Multi-account and device behavior​

If the product allows multiple accounts or role switching, define:

  • whether sessions are cached per account
  • how account switching clears volatile state
  • whether notifications and deep links are account-scoped
  • how background tasks behave after account changes

These details become critical once the app is used by support staff, administrators, or power users.

Security requirements​

Authentication playbooks should specify:

  • secure storage mechanism
  • biometric use cases and limitations
  • when sensitive actions require step-up auth
  • how failed attempts are handled
  • whether device trust influences access

The app should never be the only place enforcing permissions or transaction approval rules.

Observability​

Track at least:

  • login success and failure by method
  • refresh success and failure
  • session-expired frequency
  • step-up auth challenge outcomes
  • unauthorized API response rates by app version

This helps distinguish real security issues from broken client behavior.

Failure handling​

Plan for:

  • network unavailable during login
  • partial startup where local session exists but backend session is invalid
  • storage corruption or migration problems
  • clock skew or token timing issues
  • backend auth outages

The playbook should say whether to retry, degrade, or force logout in each case.

Team rule​

One auth model, one secure storage abstraction, one session state model. Multiple parallel auth implementations are almost always a long-term defect.

Pair this with Mobile Security and Deep Linking and App Routing.