Xamarin app ↔ OAuth backend: Secure Storage credential validity and refresh decision

Answer

Treat a SecureStorage.GetAsync failure (null return or a platform keystore exception) as an immediate trigger for re-authentication — do not attempt a refresh first. A storage failure means the credential is unreadable, so there is no refresh token to exchange. Silent refresh is only appropriate on a different failure mode: you successfully read a refresh token, but the access token is expired or the API returns 401.

For refresh attempts, a safe bound is: one refresh exchange per 401, one retry of the original request, and a second consecutive 401 (or an invalid_grant from the token endpoint) falls back to full re-authentication. That gives you at most two token-endpoint calls per failed request and no loop.

Why the two failure modes need separate code paths

iOS Keychain and Android Keystore entries can become unreadable after a backup/restore to a new device, or after lock-screen/biometric changes invalidate Keystore keys (behavior varies by OS version and key configuration). This is an expected lifecycle event, not a transient error — retrying GetAsync or attempting a refresh with a token you couldn't read accomplishes nothing. Route it straight to the login flow.

By contrast, a 401 with a readable refresh token usually means ordinary access-token expiry, which is exactly what the refresh token exists for.

Bounding the refresh logic

1. On API 401, attempt exactly one refresh exchange. Serialize it with a semaphore/lock so concurrent requests share one in-flight exchange — many providers use rotating, single-use refresh tokens, and parallel exchanges can invalidate the whole token family.
2. On refresh success, retry the original request once. If it 401s again, stop and re-authenticate.
3. On invalid_grant (HTTP 400 from the token endpoint), re-authenticate immediately — the refresh token is dead.
4. On network/transport errors, retry with capped exponential backoff; don't count these against the refresh budget, but don't loop forever either.
5. Add a session-level circuit breaker (e.g., max N refreshes per time window) as defense against runaway loops and provider rate limits. Reset the counter after a successful interactive login.

Storage hygiene

Store only the refresh token (and optionally the short-lived access token) in Secure Storage, request minimum scopes, and keep values small. Nothing else belongs there for API access.

Verification

• Clear app data or restore to a fresh emulator: confirm GetAsync returns null/throws and the app goes straight to login without touching the token endpoint.
• Return 401 with a valid stored refresh token: confirm exactly one exchange plus one retried request.
• Return invalid_grant: confirm the app stops refreshing and prompts for credentials.
• Log refresh calls to confirm no concurrent exchanges and that the counter resets on login.

Note: Xamarin.Essentials is in maintenance with .NET MAUI as its successor; if you migrate, re-verify the keystore-invalidation behavior, as details may differ.