Mobile API Authentication with Laravel 12 Sanctum and React Native: A Production Guide

Most "Sanctum tutorial" articles stop at here is a token, attach it to your headers, the end. Production mobile apps need biometric login, refresh-on-launch, secure storage, revocation on logout, and graceful handling when a token expires mid-action. This guide is the full story Laravel 12 on the server, React Native on the device, with the security defaults turned on.

1. Server: token issuance with abilities

// app/Http/Controllers/Api/AuthController.php
public function login(Request $request)
{
    $data = $request->validate([
        'email' => ['required', 'email'],
        'password' => ['required'],
        'device_name' => ['required', 'string', 'max:120'],
    ]);

    $user = User::where('email', $data['email'])->first();

    if (! $user || ! Hash::check($data['password'], $user->password)) {
        throw ValidationException::withMessages(['email' => 'Invalid credentials']);
    }

    $abilities = $user->isAdmin() ? ['*'] : ['read', 'write'];

    $token = $user->createToken(
        name: $data['device_name'],
        abilities: $abilities,
        expiresAt: now()->addDays(30),
    );

    return response()->json([
        'token' => $token->plainTextToken,
        'expires_at' => $token->accessToken->expires_at,
        'user' => $user->only('id', 'name', 'email'),
    ]);
}

public function logout(Request $request)
{
    $request->user()->currentAccessToken()->delete();
    return response()->noContent();
}

public function logoutOthers(Request $request)
{
    $current = $request->user()->currentAccessToken()->id;
    $request->user()->tokens()->where('id', '!=', $current)->delete();
    return response()->noContent();
}

2. Sanctum config: tighten the defaults

// config/sanctum.php
'expiration' => 60 * 24 * 30,        // 30 days, not null
'token_prefix' => env('SANCTUM_TOKEN_PREFIX', 'lpt_'),
'middleware' => [
    'authenticate_session' => Laravel\Sanctum\Http\Middleware\AuthenticateSession::class,
],

// Add a hashed prefix so tokens are scannable in GitHub secret-scanning (Sanctum 12+).

3. React Native: secure token storage

Never store tokens in AsyncStorage it is plaintext on disk. Use react-native-keychain on iOS/Android, which backs onto the Keychain and Keystore respectively.

// lib/auth.ts
import * as Keychain from 'react-native-keychain';

const SERVICE = 'app.example.com';

export async function saveToken(token: string, expiresAt: string) {
    await Keychain.setGenericPassword(
        'auth',
        JSON.stringify({ token, expiresAt }),
        {
            service: SERVICE,
            accessControl: Keychain.ACCESS_CONTROL.BIOMETRY_CURRENT_SET_OR_DEVICE_PASSCODE,
            accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
        }
    );
}

export async function loadToken(): Promise<{ token: string; expiresAt: string } | null> {
    const result = await Keychain.getGenericPassword({ service: SERVICE });
    if (!result) return null;
    return JSON.parse(result.password);
}

export async function clearToken() {
    await Keychain.resetGenericPassword({ service: SERVICE });
}

4. The fetch wrapper: refresh, retry, revoke

// lib/api.ts
import { loadToken, clearToken } from './auth';

const BASE_URL = 'https://api.example.com';

export async function api(path: string, init: RequestInit = {}): Promise<Response> {
    const stored = await loadToken();
    if (!stored) throw new Error('NOT_AUTHENTICATED');

    const headers = new Headers(init.headers);
    headers.set('Authorization', `Bearer ${stored.token}`);
    headers.set('Accept', 'application/json');

    const response = await fetch(`${BASE_URL}${path}`, { ...init, headers });

    if (response.status === 401) {
        await clearToken();
        // Tell the navigation root to bounce to /login
        global.dispatchEvent(new Event('auth:expired'));
        throw new Error('SESSION_EXPIRED');
    }

    return response;
}

5. Biometric unlock for sensitive actions

import ReactNativeBiometrics from 'react-native-biometrics';

const rnBiometrics = new ReactNativeBiometrics({ allowDeviceCredentials: true });

export async function requireBiometric(reason: string): Promise<boolean> {
    const { available } = await rnBiometrics.isSensorAvailable();
    if (!available) return true; // device cannot prompt — fall back to password gate

    const { success } = await rnBiometrics.simplePrompt({ promptMessage: reason });
    return success;
}

// Usage before a transfer:
const ok = await requireBiometric('Confirm transfer of $250');
if (!ok) return;
await api('/transfers', { method: 'POST', body: JSON.stringify(payload) });

6. Active sessions UI — server side

public function sessions(Request $request)
{
    return $request->user()->tokens()
        ->select('id', 'name', 'last_used_at', 'expires_at', 'created_at')
        ->orderByDesc('last_used_at')
        ->get()
        ->map(fn ($t) => [
            'id' => $t->id,
            'device' => $t->name,
            'last_used' => $t->last_used_at?->diffForHumans(),
            'is_current' => $t->id === $request->user()->currentAccessToken()->id,
        ]);
}

public function revokeSession(Request $request, int $id)
{
    $request->user()->tokens()
        ->where('id', $id)
        ->where('id', '!=', $request->user()->currentAccessToken()->id)
        ->delete();

    return response()->noContent();
}

7. Production checklist