Where Should Your Rork App Store Auth Tokens? expo-secure-store and a Biometric Gate

Put biometrics in front of the read

Encrypting the token at rest doesn't stop anyone who opens the app from continuing the session. Before a screen that touches money or personal data, you often want the token read itself to require a biometric check.

Use expo-local-authentication as a gate immediately before pulling from SecureStore.

npx expo install expo-local-authentication

// lib/authGate.ts
import * as LocalAuthentication from "expo-local-authentication";
 
export async function canUseBiometrics(): Promise<boolean> {
  const hasHardware = await LocalAuthentication.hasHardwareAsync();
  const isEnrolled = await LocalAuthentication.isEnrolledAsync();
  return hasHardware && isEnrolled;
}
 
export async function requireBiometricUnlock(): Promise<boolean> {
  // If the device has no biometrics enrolled, you may choose not to block here
  if (!(await canUseBiometrics())) return true;
 
  const result = await LocalAuthentication.authenticateAsync({
    promptMessage: "Unlock the app",
    fallbackLabel: "Use passcode",
    // After a few biometric failures, fall back to the device passcode
    disableDeviceFallback: false,
  });
  return result.success;
}

The read path only fetches the token after passing the gate.

// flow before entering a sensitive screen
import { requireBiometricUnlock } from "./lib/authGate";
import { getAccessToken } from "./lib/secureToken";
 
async function unlockAndLoad() {
  const ok = await requireBiometricUnlock();
  if (!ok) {
    // On failure, never touch the token; stay on the lock screen
    return { authed: false } as const;
  }
  const token = await getAccessToken();
  return { authed: !!token, token } as const;
}

The point is that on failure you never load the token into memory. Call getAccessToken() before the gate and the biometric check becomes theater. The ordering is the design.

SecureStore also has a requireAuthentication: true option that enforces auth on read at the OS level. Its behavior is sensitive to device differences, though — I hit rough edges on emulators and certain Android devices. Because I want to control the fallback myself, I keep LocalAuthentication out front as shown above.

The size limit landmine

I tripped here once. Android's SecureStore can fail to save when the value is large (roughly past 2KB). I had stuffed a JWT full of claims, concatenated the refresh token, and packed it all into one key — which produced a low-reproducibility bug where the device alone returned null.

The fix is mundane: split long values, or don't pack them in the first place.

"Only the secrets, minimal, in separate keys." Knowing SecureStore is size-sensitive saves you hours of chasing a mysterious save failure.

Migrate off AsyncStorage exactly once

Existing users still have tokens in AsyncStorage. If an update changes the storage location, run the migration once on first launch and delete the old copy afterward.

// lib/migrateTokens.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import { saveTokens } from "./secureToken";
 
const MIGRATION_FLAG = "auth.migratedToSecureStore.v1";
 
export async function migrateTokensIfNeeded() {
  const done = await AsyncStorage.getItem(MIGRATION_FLAG);
  if (done) return;
 
  const legacyAccess = await AsyncStorage.getItem("accessToken");
  const legacyRefresh = await AsyncStorage.getItem("refreshToken");
 
  if (legacyAccess && legacyRefresh) {
    await saveTokens(legacyAccess, legacyRefresh);
    // leave no plaintext trace behind
    await AsyncStorage.multiRemove(["accessToken", "refreshToken"]);
  }
  await AsyncStorage.setItem(MIGRATION_FLAG, "1");
}

Version the flag (v1). When you later change the key layout, you add a v2 migration and roll forward in steps. Wrap this in try/catch so a failed migration doesn't crash the app, and on failure don't set the flag — let it retry next launch. Retrying is safer than swallowing the error.

Sign-out: what must not stay on the device

Calling deleteItemAsync on sign-out is obvious. What's easy to miss is everything else: the token still in memory, the header your API client holds, the cached "signed-in user name." Leave those and the next person sees a flash of the previous session.

async function signOut() {
  await clearTokens();                 // remove from SecureStore
  await AsyncStorage.multiRemove([     // and personal data on the settings side
    "user.displayName",
    "user.lastSyncedAt",
  ]);
  apiClient.setAuthHeader(null);       // drop the in-memory header
  queryClient.clear();                 // discard fetched-data cache
}

Reframe sign-out as "return the device to its pre-login state" rather than "delete the token," and the leftovers become easier to spot. I revisit this list whenever I add a feature: if I now persist a new piece of personal data, I add a line to this cleanup too.

Small gotchas from production

A few places where the device and the simulator disagree.

On the iOS simulator the biometric dialog appears, but unless you enable Features > Face ID > Enrolled it fails every time. Check that before you suspect your own code.

Repeated biometric failures trigger a lockout, after which authenticateAsync stops returning success or failure for a while. Setting disableDeviceFallback: false so users can escape to the device passcode keeps them from getting stuck.

With WHEN_UNLOCKED_THIS_DEVICE_ONLY, tokens do not carry over when the user upgrades phones. That's the safe, intended behavior — but it's kind to tell users up front that a new device means signing in again. A single line in the release notes cut my support questions noticeably.

If you're starting, isolate the tokens into SecureStore first. The biometric gate is a layer you stack on top, so there's no rush until the foundation is solid. Thanks for reading — I hope it helps if you're stuck on the same thing.