DEV Community: Puneetpal Arneja

Mobile App Security Checklist 2026 (Banking & Fintech)

Puneetpal Arneja — Mon, 09 Nov 2026 15:10:18 +0000

Short answer: a banking app security checklist should follow the OWASP MASVS v2 control groups: STORAGE, CRYPTO, AUTH, NETWORK, PLATFORM, CODE, RESILIENCE and PRIVACY. Keep secrets in the Keychain or Android Keystore, let the server make every authorization decision, enforce TLS, treat jailbreak and root detection as defense in depth, and verify it all with the OWASP MASTG.

In a banking app a leak is both a regulatory event and a direct financial loss. This checklist covers the client-side controls I check when building or auditing fintech and banking apps, from authentication to incident response, and maps each one to the OWASP Mobile Application Security Verification Standard (MASVS) so it lines up with the standard security reviewers already use.

The server half (token lifecycle, policy enforcement, rate limiting and abuse control) is in the Laravel API security checklist. The two are meant to be read together: a hardened app in front of an API that trusts the client is still an open attack path. For how these controls fit a regulated release process, see mobile architecture audits, and for having them built into a new banking app from the start, see fintech and banking app development.

How does OWASP MASVS map to a banking app?

MASVS v2 dropped the old L1/L2/R verification levels from the standard itself and organizes requirements into eight control groups. The levels live on as MAS testing profiles, which decide how strictly each control is tested; a banking app is what the stricter profiles exist for. The table maps each group to what it means for a banking app, the concrete platform check, and the section that covers it.

MASVS group	What it means for a banking app	Concrete iOS / Android check	Section
MASVS-STORAGE	Tokens, account data and statements never land in plaintext files, backups, caches or the clipboard.	iOS: Keychain with a ThisDeviceOnly accessibility class; files under NSFileProtectionComplete. Android: Keystore-wrapped keys; allowBackup off or dataExtractionRules excluding sensitive files.	3
MASVS-CRYPTO	Platform crypto with modern algorithms, and keys that are never hardcoded in the binary.	iOS: CryptoKit AES-GCM, keys in the Secure Enclave or Keychain. Android: Keystore keys, StrongBox where the device has it.	3
MASVS-AUTH	The server decides who the user is; biometrics unlock a credential instead of returning a yes/no.	iOS: Keychain item with SecAccessControl (.biometryCurrentSet). Android: Keystore key with setUserAuthenticationRequired, used through BiometricPrompt with a CryptoObject.	1
MASVS-NETWORK	TLS everywhere, no cleartext exceptions, and a deliberate decision on certificate pinning.	iOS: App Transport Security with no NSAllowsArbitraryLoads. Android: Network Security Config with cleartextTrafficPermitted="false", optional pin-set with an expiration.	2
MASVS-PLATFORM	Balances and account numbers do not leak through the app switcher, screenshots, WebViews or IPC.	iOS: cover the window when the scene resigns active; restrict WKWebView JavaScript. Android: FLAG_SECURE on sensitive activities; exported="false" on components that do not need it.	1, 5
MASVS-CODE	Supported OS versions are enforced, dependencies are current, and all input from outside the app is validated.	Both: minimum OS policy, forced-update path, SDK inventory, deep link and push payload validation.	5, 7
MASVS-RESILIENCE	Tampering, hooking and debugging are made expensive, as defense in depth rather than as a primary control.	iOS: App Attest, jailbreak and debugger checks. Android: Play Integrity API, root checks, R8 shrinking and obfuscation.	4, 5
MASVS-PRIVACY	Collect the minimum personal data, keep it out of logs and analytics, and disclose what third-party SDKs do.	iOS: privacy manifest and os_log privacy redaction. Android: Play Data safety form, R8 rules stripping debug logs.	6

1. Authentication & Session Management

MASVS-AUTH, MASVS-STORAGE, MASVS-PLATFORM

Most account takeovers start with a stolen credential or a lifted token, so these controls limit how long any single secret is useful and where it can be used.

Token Lifecycle

Short-lived access tokens (around 15 minutes) with refresh tokens in the 7 to 30 day range (with Sanctum that means a short token expiry plus a rotate endpoint, or Passport; see the Laravel checklist): short enough that a token captured from a proxy log is dead before anyone reads it, long enough that refresh happens between sessions rather than mid-transfer
Rotate the refresh token on every use, and revoke the whole family if a rotated-out token is presented again; that is the signal a token was copied
Invalidate tokens server-side on logout. Expiry alone leaves a stolen token valid until the clock runs out
Keep access tokens in memory only, never in UserDefaults or SharedPreferences
Store refresh tokens in the iOS Keychain with kSecAttrAccessibleWhenUnlockedThisDeviceOnly, or encrypted with an Android Keystore key
For high-value apps, bind the session to the device: a non-exportable Secure Enclave or Keystore key, registered with the server at enrolment, signs each request, so a copied token cannot be replayed elsewhere

Biometric & MFA

Treat Face ID, Touch ID and Android biometrics as a local convenience that unlocks a stored credential. The server authenticates the credential; a biometric result alone never grants access
Make biometrics unlock a secret instead of returning a boolean: a Keychain item protected by SecAccessControl with .biometryCurrentSet on iOS, or a Keystore key with setUserAuthenticationRequired(true) used through BiometricPrompt with a CryptoObject on Android. A hooked evaluatePolicy callback then unlocks nothing, and .biometryCurrentSet invalidates the item if a new fingerprint or face is enrolled
Require a second factor for transfers above a threshold, password changes, and new payees
Step-up within a session: re-authenticate before sensitive operations even if the session is fresh
Prefer TOTP or push approval over SMS codes. SIM-swap fraud is the standard way SMS OTP is defeated, and it is cheap

Passkeys Instead of Passwords

Passkeys (FIDO2/WebAuthn) remove the password from sign-in, so there is nothing to phish, reuse or stuff. The private key never leaves the device or the user’s credential manager, and each passkey is bound to your domain, so a look-alike site cannot use it
On iOS 16 and later use ASAuthorizationPlatformPublicKeyCredentialProvider with an associated domain (webcredentials:). On Android 9 and later use the Credential Manager API. Both talk to the same WebAuthn relying-party endpoints on your server
Synced passkeys (iCloud Keychain, Google Password Manager) survive a lost phone, which matters for account recovery. NIST SP 800-63B-4 accepts synced passkeys at AAL2 when the sync service meets its requirements; for the highest assurance, keep a device-bound key such as the Secure Enclave or Keystore key used for session binding above
Roll out alongside the existing login, not as a replacement on day one. Offer passkey creation after a successful sign-in, keep step-up checks for transfers and new payees, and make recovery at least as strong as sign-in, since a weak reset flow undoes the passkey
The passkey, biometric, device-binding and recovery code for all of this is in secure authentication best practices for fintech apps

Session Controls

Auto-lock after a short inactivity window; 2 to 5 minutes is typical for banking apps. Make it configurable only within that range
Limit concurrent sessions per user, show the user their active devices, and let them sign one out. On a Laravel backend, laravel-device-tokens gives you one Sanctum token per device with sign-out per device or everywhere

Screenshot and App-Switcher Masking

iOS takes a snapshot of the screen for the app switcher when the app goes to the background. Cover the window with a privacy view in sceneWillResignActive and remove it in sceneDidBecomeActive, so balances and account numbers never reach that snapshot
iOS has no public API to block screenshots. Detect screen recording and mirroring with UIScreen.isCaptured, react to userDidTakeScreenshotNotification, and hide sensitive values while capture is active
On Android, set WindowManager.LayoutParams.FLAG_SECURE on sensitive activities. It blocks screenshots, screen recording and the recents-screen preview in one step

2. API & Network Security

MASVS-NETWORK

Transport Security

TLS 1.2 or later only, enforced at the server. ATS already refuses anything older on iOS, so the client side is mostly about not adding exceptions
App Transport Security with no exceptions. NSAllowsArbitraryLoads in a production Info.plist is a finding on its own
On Android, ship a Network Security Config with cleartextTrafficPermitted="false" and no user-added CAs trusted in release builds (scope debug-overrides to debug only)
Validate the full certificate chain. A URLSessionDelegate or TrustManager that accepts any certificate to make a staging environment work has a way of surviving into release

Certificate Pinning: Trade-offs

Pinning stops interception by a mis-issued or user-installed certificate. It does not stop an attacker who controls the device, and a badly managed pin locks every user out on the day a certificate renews.

Pin the public key (SPKI hash) rather than the whole certificate, so renewing a certificate with the same key does not break the app
Include at least one backup pin for a key that is not yet in use, so rotation does not force an app update
iOS: use NSPinnedDomains in the ATS configuration or validate in a URLSessionDelegate trust challenge. Android: use a <pin-set> with an expiration date in Network Security Config, so an outdated build falls back to normal TLS validation rather than failing closed
Have a remote way to update or relax pins, and a runbook for certificate rotation, before you ship pinning

Request Integrity

TLS already protects requests in transit. Request signing earns its place as device binding: sign with the non-exportable Secure Enclave or Keystore key from section 1, so a bearer token is useless off the device it was issued to. An HMAC with a per-session secret delivered over the same TLS channel adds little
With signing in place, include a timestamp and nonce in the signed payload and reject anything outside a few-minute window, so a captured request cannot be replayed
Send tokens only in the Authorization: Bearer header. Query strings end up in access logs, proxies, and crash reports
Expect HTTP 429 with Retry-After and honour it with backoff. A client that retries instantly turns a brief server incident into a longer one
Error responses must not leak stack traces, SQL, or whether an account exists. Field-level validation messages are fine; “no account with that email” is not

3. Data Storage & Encryption

MASVS-STORAGE, MASVS-CRYPTO

What Goes Where on iOS

Keychain: tokens, passwords, private keys, PINs. Use kSecAttrAccessibleWhenUnlockedThisDeviceOnly so items are never migrated to another device through a backup
Core Data / SQLite: financial records, encrypted with SQLCipher or protected with the Data Protection class NSFileProtectionComplete. Data Protection only makes the file unreadable while the device is locked; data that must stay unreadable on a jailbroken, unlocked device needs application-level encryption too
UserDefaults: non-sensitive UI preferences only. It is a plist on disk and lands in backups
Cached images and PDFs: disable or clear the URLCache for sensitive responses and mark files with NSFileProtectionComplete. Downloaded statements are the classic leak here
Backups: set isExcludedFromBackup on files that should not leave the device
Clipboard: copy sensitive values with UIPasteboard options .localOnly and an .expirationDate (60 seconds is enough for an account number), so they do not sync through Universal Clipboard or linger

What Goes Where on Android

Android Keystore: generate keys inside the Keystore so the key material is non-exportable; request StrongBox with setIsStrongBoxBacked(true) where the device supports it and fall back when it does not
App-private storage: encrypt tokens and records with a Keystore-held key before writing them. Never plain SharedPreferences or external storage
Backups: set android:allowBackup="false", or use dataExtractionRules (Android 12+) to exclude sensitive files from cloud backup and device-to-device transfer
Clipboard: mark copied sensitive values with ClipDescription.EXTRA_IS_SENSITIVE (Android 13+) so they are not shown in the clipboard preview

Encryption Standards

AES-256-GCM for symmetric encryption, which gives confidentiality and integrity in one primitive (CryptoKit AES.GCM on iOS, a Keystore-backed Cipher on Android). Never reuse a nonce with the same key
Use the Secure Enclave for private keys when available. It holds P-256 keys only, so wrap symmetric keys with an enclave key rather than storing them inside it
Never hardcode keys. Generate them in the Keystore or Secure Enclave; derive from a user secret only when the data must survive without the server
Zero sensitive buffers after use. Swift and Kotlin strings cannot be reliably zeroed and may be copied around memory, so keep secrets in mutable byte arrays you can wipe

4. Device & Runtime Integrity

MASVS-RESILIENCE

Jailbreak and Root Detection: Defense in Depth, Not a Control

On a jailbroken or rooted device the sandbox is gone: Keychain items can be dumped, pinning bypassed with one Frida script, and any method hooked. Every detection check runs on that same device, so each one can be patched out. I treat detection as friction plus a risk signal for the server, never as the thing that keeps an account safe. Layered checks still raise the cost:

Look for jailbreak artifacts: package manager apps, the /var/jb prefix used by rootless jailbreaks, and injected libraries listed by _dyld_get_image_name. Hardcoded lists of 2015-era paths are the first thing attackers patch
Attempt to write outside the app sandbox; it should fail on a stock device
Check whether fork() succeeds; it is denied to sandboxed apps on stock iOS
On Android, check for su binaries, test-keys builds, Magisk and other root-management packages, and whether SELinux is enforcing
Verify the app’s own code signature and bundle identifier at runtime; repackaged apps are a common distribution path for banking malware
Combine several independent signals and send them to the server. A single boolean in the app is one patch away from always-false
On detection, degrade rather than refuse: warn the user, disable transfers and payee changes, and log the event server-side with the device signals

Runtime Attack Detection

Debugger detection on iOS via sysctl (the P_TRACED flag) or ptrace(PT_DENY_ATTACH). ptrace is not public API, so it is called through dlsym, and both checks are trivially patched. A speed bump, not a gate
For Objective-C code paths that matter, confirm at runtime that method_getImplementation still points at your own code. Swift final classes and structs are harder to swizzle in the first place
Detect the simulator and emulators, and never ship production credentials or endpoints in builds that can run there
Use App Attest (DeviceCheck framework, iOS 14+). It creates a Secure Enclave key attested by Apple; your server verifies the attestation once and a per-request assertion after that. It is the strongest available signal that a request came from your unmodified app
On Android, use the Play Integrity API and verify its verdict on your server, not in the app. Decide in advance what each verdict level (device, app, account) is allowed to do

5. Code Hardening & Obfuscation

MASVS-CODE, MASVS-RESILIENCE, MASVS-PLATFORM

Xcode release builds on arm64 already produce position-independent executables with stack protection. Verify nothing in the build settings turned them off (otool -hv shows the PIE flag), and never ship Swift built with -Ounchecked, which removes overflow and precondition checks
Strip symbols from release builds (Deployment Postprocessing and Strip Linked Product set to YES) and upload the dSYM to your crash reporter, so stack traces are readable to you and not to whoever downloads the IPA
Obfuscate sensitive strings and class names where the threat model justifies it: iXGuard on iOS, DexGuard on Android. R8 alone shrinks and renames; it is not meaningful obfuscation against a determined reverser
Remove NSLog, print, and debug output from production builds. A #if DEBUG wrapper is enough on iOS; section 6 has the Android R8 rule
Restrict JavaScript in WKWebView (WKWebpagePreferences.allowsContentJavaScript = false) unless the page needs it, and never expose a native bridge (WKScriptMessageHandler, addJavascriptInterface) to content you do not control
Treat deep links, universal and app links, and push payloads as untrusted input: validate every parameter and never let a deep link complete an action by itself. Set android:exported="false" on components that do not need to be reachable
Enforce a minimum supported OS version and keep a forced-update path, so a build with a known vulnerability can be retired without waiting for users
Inventory third-party SDKs. Each one ships with your signing identity and permissions; review what it collects, how often it updates, and whether it has a privacy manifest

6. Logging: What NOT to Log

MASVS-STORAGE, MASVS-PRIVACY

Logs are the storage location nobody threat-models. On iOS, NSLog and unredacted os_log output goes to the unified log, readable from any Mac the phone is plugged into and included in sysdiagnose bundles. Server logs are often less protected than the database they describe.

Never Log

Full account numbers, card numbers, CVV
Auth tokens, refresh tokens, session IDs
Passwords (even hashed)
Full API request/response bodies
PII: SSN, DOB, full address
Biometric data or persistent device identifiers

Safe to Log

Event types (login_attempt, transfer_initiated)
Masked identifiers (last 4 of account)
Error codes and HTTP status codes
Request duration and latency
Feature flags and A/B experiment IDs
Random per-launch correlation IDs that are not the authenticated session identifier

Secure Logging in the App

On iOS, use Logger / os_log and keep dynamic values at the default .private level so they are redacted outside a debugger. Marking a value .public is a code review item
On Android, strip Log.d and Log.v from release builds with an R8 -assumenosideeffects rule on android.util.Log
Check what crash reporters and analytics SDKs capture. Breadcrumbs, network logging, and session replay can collect request bodies and screen contents by default

Server-Side Audit Logging

Log every authentication event with timestamp, IP, device identifier, and outcome
Log high-value transactions with user ID, amount, and a masked counterparty
Log admin actions and configuration changes with the actor
Ship logs to a SIEM (Splunk, Datadog, CloudWatch) with retention set by your compliance regime. PCI DSS requires twelve months with three months immediately available; treat that as the floor
Alert on brute-force patterns, impossible travel, and unusual transaction volume per account, not just per system

7. Incident Response Readiness

MASVS does not cover incident response, but a banking app cannot ship without it. The three kill switches below separate a two-hour incident from a two-week one, because each removes the dependency on users updating the app.

Kill Switches

Remote feature flags that can disable any feature (transfers, new payees, a vulnerable SDK) without an app update
A forced-update mechanism driven by a server-controlled minimum build, so a compromised version can be blocked the same day
Server-side session revocation for one user or every user, tested in staging before you need it

Detection & Response Playbook

Define P0/P1/P2 severity levels with response SLAs before launch
Name a single incident owner with authority to pull the kill switches
Prepare user notification templates for credential-exposure scenarios in advance; writing them during the incident is how they go out late
Know the regulatory clocks before launch. GDPR gives 72 hours to notify the supervisory authority; the US banking agencies’ Computer-Security Incident Notification rule requires a banking organization to notify its primary federal regulator within 36 hours of determining that a notification incident has occurred (a bank service provider must notify the bank as soon as possible); PCI DSS card-brand rules and US state breach laws each set their own deadlines
Run a tabletop exercise each quarter against a realistic scenario: a leaked signing key, a malicious SDK update, a credential-stuffing run

How do you test a banking app against MASVS?

MASVS says what to achieve; the OWASP Mobile Application Security Testing Guide (MASTG) says how to verify it, with iOS and Android test cases organized by the same control groups. I use it to structure internal reviews and to scope external penetration tests, so both produce evidence in the same shape.

Scope the review by MASVS group, and agree which MAS testing profile applies before testing starts
Run static checks on every release build: entitlements, ATS and Network Security Config, exported components, backup flags, hardcoded secrets
Run dynamic checks on a test device: inspect what ends up in the Keychain, Keystore, files, logs and the app-switcher snapshot
Record results per control so the evidence is ready for compliance and audit reviews

Mobile App Penetration Testing Checklist for Fintech Apps

When I scope a pen test on a banking or fintech app, iOS and Android, these are the checks I make sure are in it. Each one maps back to a section above.

Traffic: route the app through an intercepting proxy, confirm TLS is enforced, and try to bypass certificate pinning
Storage: pull the app container and check the Keychain or Keystore, databases, caches, logs and screenshots for tokens or personal data
API authorization: replay and edit requests to read another user’s accounts, change amounts or skip steps; the server must refuse every one
Session: confirm tokens expire, logout revokes them on the server, and a stolen token cannot be used from a second device
Runtime: run on a jailbroken or rooted device with Frida, and check that tampering is detected and reported to the server
Binary: decompile the release build for hardcoded keys, test endpoints, debug menus and verbose logging
Platform: check deep links, exported Android components, pasteboard use and backups for data that leaks out of the app

Security Audit Checklist Summary

Short-lived tokens + refresh rotation
Biometrics unlock a Keychain/Keystore secret
TLS 1.2+, ATS and Network Security Config
Certificate pinning with backup pins
Device-bound request signing
Keychain with device-only access
AES-256-GCM encryption at rest
App-switcher masking and FLAG_SECURE
Jailbreak/root detection (layered)
App Attest / Play Integrity
Release build hardening verified
Symbols stripped from release
No PII in any log output
SIEM with anomaly alerts
Remote kill switches in place
Incident response playbook ready

Need a Security Audit for Your Mobile Banking App?

If you want this checklist run against your app, see mobile architecture audits. If you are building the app, or a new module in it, see fintech and banking app development.

Request a Security Audit
View Audit Services

Originally published at puneetpal.dev.

Laravel API Security Checklist 2026 for Mobile Apps

Puneetpal Arneja — Mon, 02 Nov 2026 17:17:10 +0000

A Laravel API used by a mobile app is secure when Sanctum tokens expire and carry narrow abilities, every record lookup is checked by a policy, input passes through validated() and $fillable, named rate limiters guard login and writes, APP_DEBUG is off with secrets out of git, and composer audit gates every deploy. Logging and alerting close the loop.

Mobile backends fail security reviews for the same few reasons: tokens that never expire, lookups that check identity but not ownership, no limits on login or OTP endpoints, and logs that cannot answer “who read this record?” This is the order I work through when hardening a Laravel API behind a mobile app. For the design side (versioning, response shape, pagination), see Laravel as a backend for mobile apps.

Checklist mapped to the OWASP API Security Top 10 (2023)

The OWASP API Security Top 10 is the list most security reviewers work from. Each risk maps to a Laravel control and a section below.

OWASP risk	Laravel control	Section
API1 Broken Object Level Authorization	Policies plus queries scoped to the owner	3
API2 Broken Authentication	Sanctum token expiry, abilities, revocation, login throttling	2, 5
API3 Broken Object Property Level Authorization	$fillable, validated() input, API Resources for output	4
API4 Unrestricted Resource Consumption	Named rate limiters, page-size caps, upload limits	5, 7
API5 Broken Function Level Authorization	Gates and policies on admin routes, token abilities	2, 3
API6 Unrestricted Access to Sensitive Business Flows	Per-account limits on signup, OTP, checkout	5
API7 Server Side Request Forgery	Allowlist outbound URLs fetched on a user’s behalf	7
API8 Security Misconfiguration	APP_DEBUG off, secrets out of git, HTTPS, trusted proxies	6
API9 Improper Inventory Management	route:list review, retire old API versions	10
API10 Unsafe Consumption of APIs	Validate third-party and webhook payloads, timeouts	7, 9

1. Threat Model Before Feature Build

Spend an hour per feature area on four questions before the endpoints exist, and write the answers down:

Actors: end user, support staff, admin, partner integrations, and the attacker holding a stolen phone with a valid token.
Data: what is regulated or damaging if leaked (PII, payment metadata, health signals, location history).
Likely abuse: credential stuffing, OTP guessing, scraping of list endpoints, replay of a captured token.
Blast radius: what one leaked token can read or change, and how fast you can revoke it.

The useful output is a table of endpoints with three columns: needs step-up auth, needs a per-account rate limit, touches regulated data. Apply the controls below against that table, not uniformly.

2. Authentication and Token Lifecycle

With Laravel Sanctum, the most common gap is that personal access tokens never expire: expiration in config/sanctum.php is null by default. The config value applies to every token; the third argument to createToken() sets a per-token expiry. Expired rows stay in the table until sanctum:prune-expired runs.

<?php
// config/sanctum.php
return [
    // ...
    'expiration' => 60 * 24 * 30, // minutes; null means tokens never expire
];

// AuthController: issue one token per device with narrow abilities and its own expiry
$token = $user->createToken(
    $request->device_name,
    ['orders:read', 'orders:write'],
    now()->addDays(30),
)->plainTextToken;

// Require an ability on a route (alias the abilities middleware in bootstrap/app.php)
Route::post('/orders', [OrderController::class, 'store'])
    ->middleware(['auth:sanctum', 'abilities:orders:write']);

// Logout revokes only this device's token
$request->user()->currentAccessToken()->delete();

// Password reset, email change, "sign out everywhere": revoke all of them
$user->tokens()->delete();

// routes/console.php: delete expired token rows
Schedule::command('sanctum:prune-expired --hours=24')->daily();

Beyond expiry:

Sanctum has no refresh tokens. Either accept re-login at expiry, or add a /auth/token/rotate endpoint that issues a new token and deletes the old one in one transaction. Real OAuth2 refresh semantics are Passport’s job.
One token per device, named after the device, so a lost phone can be revoked alone. Device binding (a Secure Enclave or Keystore key that signs requests) is worth the client work only where a replayed token is a real threat, such as payments.
Step-up for high-risk actions. password.confirm is session-based, so for a token API store a reauthenticated_at timestamp on the token and require it to be recent before transfers, payout changes, or email changes.
Login and reset responses must not reveal whether an account exists: same message, same timing.

3. Authorization Must Be Explicit and Centralized

The most common API flaw, Broken Object Level Authorization, is simply this: a signed-in user changes an ID in the URL and reads someone else’s record. Authentication passed; nothing checked ownership. Fix it with policies or by scoping the query to the caller.

class OrderController extends Controller
{
    // Vulnerable: any authenticated user can fetch any order by ID
    public function showUnsafe(string $id): OrderResource
    {
        return new OrderResource(Order::findOrFail($id));
    }

    // Fixed with a policy (OrderPolicy::view)
    public function show(Order $order): OrderResource
    {
        Gate::authorize('view', $order);

        return new OrderResource($order);
    }

    // Or scope the lookup to the caller's own records
    public function showOwned(Request $request, string $id): OrderResource
    {
        return new OrderResource($request->user()->orders()->findOrFail($id));
    }
}

One policy class per model, and scoped relationships for list endpoints too. An index that starts from Order::query() is the same bug spread across a page.
Function-level checks on admin routes with can: middleware or a gate, separate from token abilities. Abilities say what a device may do; policies say what the user may do.
ULIDs or UUIDs (HasUlids) in public URLs. Not a substitute for the policy, but it stops someone walking /orders/1 to /orders/99999 in an afternoon.
One feature test per resource that fetches another user’s record and asserts 403 or 404. It is the cheapest test in the suite and catches the refactor that drops a policy call.

4. Input Validation and Output Minimization

Every write endpoint gets a Form Request, and only validated fields reach the model.

Declare $fillable on every model and pass $request->validated(), never $request->all(). Otherwise a client sets is_admin or user_id by adding a key to the JSON body.
A max: on every string and array rule, and File::types([...])->max(...) on uploads. Unbounded input is how a free-text field becomes a 50 MB request.
Eloquent binds parameters, so SQL injection enters through DB::raw, whereRaw, or a user-chosen column name. Bind values; allowlist column names, which cannot be bound.
$hidden for password, remember_token, and internal flags, and an API Resource for every response. Returning a model directly leaks every column the day someone adds one.

// Mass assignment: only fields that passed validation
$order->update($request->validated());

// Raw SQL: bind values, never interpolate them
Order::whereRaw('total > ?', [$minimum])->get();

// Column names cannot be bound, so allowlist them
$sort = in_array($request->query('sort'), ['created_at', 'total'], true)
    ? $request->query('sort')
    : 'created_at';

Order::orderBy($sort)->paginate(25);

5. Rate Limiting and Abuse Controls

A single global limit protects the server and nothing else. Limits need to match the endpoint:

Login, password reset, OTP request: per account plus IP, and per IP alone. Five a minute per account is a normal start.
OTP verification: a handful of attempts per code, then invalidate it. A six-digit code with unlimited tries is a million-row lookup table.
Search and feed endpoints: a per-user burst limit so one client cannot scrape at full speed.
Page sizes capped server-side (min($request->integer('per_page', 25), 100)) so one request cannot pull a table.
Business flows (signup, checkout, referral): per-account counts over a day, not just per minute.

Laravel’s named rate limiters let each group key its limit by user, IP, or both. Key by user ID whenever the caller is authenticated; carrier NAT puts thousands of phones behind one IP, so IP-only limits lock out real users while barely slowing a proxy pool.

// AppServiceProvider::boot()
RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});

RateLimiter::for('login', function (Request $request) {
    return [
        Limit::perMinute(5)->by(strtolower((string) $request->input('email')).'|'.$request->ip()),
        Limit::perMinute(20)->by($request->ip()),
    ];
});

// routes/api.php
Route::post('/login', LoginController::class)->middleware('throttle:login');

Two operational details. Counters live in the cache, so production needs Redis or another shared store; the file driver keeps separate counts per server. And throttle already sends Retry-After on 429; make sure the body is your JSON error envelope so the app shows a message instead of a decode failure.

6. Data Protection, Secrets, and Production Config

Security Misconfiguration findings come almost entirely from this list, and each is a five-minute fix.

APP_DEBUG=false and APP_ENV=production, with config:cache on deploy. The debug error page prints stack traces, request data, and environment values to whoever triggered the exception.
.env never committed; secrets injected from the host’s secret store. APP_PREVIOUS_KEYS lets you rotate APP_KEY without breaking existing encrypted data.
Trusted proxies configured ($middleware->trustProxies(...)) behind a load balancer. Otherwise $request->ip() is the balancer’s address, every user shares one IP, and the per-IP limiters in section 5 lock everyone out at once.
TLS at the load balancer with HSTS, and URL::forceScheme('https') so generated links never downgrade.
The encrypted cast for third-party tokens and similar secrets. Encrypted columns cannot be indexed, so add a hashed blind-index column if you need to look a value up.
config/cors.php tight for any web frontend, knowing that native HTTP clients ignore CORS entirely. It is not an access control for the app.

7. Secure File Upload and External Integration Boundaries

Uploads and outbound requests are where an API starts touching things it does not control.

Validate uploads with File::types() and max(). Laravel’s mimes rule inspects file contents, not the extension.
Uploads on a private disk, served through temporary URLs; nothing user-supplied under public/. For large files, let the app upload straight to S3 with a presigned URL (see the backend design guide) and validate size and type afterwards.
If the API fetches a URL the user supplies (image import, link preview, webhook target), that is a server-side request forgery surface. Allow only http and https, resolve the host and reject loopback, private, and link-local ranges including IPv6, re-check after each redirect, and set a short timeout.
Http::timeout(), connectTimeout(), and a bounded retry() on every third-party call. A partner API that hangs for 60 seconds takes your PHP-FPM pool with it.
Validate third-party responses as strictly as client input; a buggy upstream is API10 for a reason.

8. Logging, Monitoring, and Alerting

After an incident a log has to answer “which user, from which device, read or changed which record, and when?” Build that context in from day one.

A middleware that generates a request ID and calls Log::withContext() with it plus the user ID, client platform, and build. In Laravel 11+, the Context facade carries the same values into queued jobs, so a job log traces back to the request that queued it.
Listen for Illuminate\Auth\Events\Failed and Lockout, and log 403s from the exception handler with user, route, and object ID. A user collecting 403s across sequential IDs is someone probing for the bug in section 3.
Never log the Authorization header, tokens, passwords, OTP codes, or full request bodies. Check what your error reporter captures; most send request data unless told not to.
Alerts on failed logins per IP and per account, 403s per user, 5xx per route, and queue backlog. Dashboards nobody is paged from are decoration.
Retention is set by your compliance regime, not disk cost. PCI DSS, for example, requires twelve months of audit logs with three months immediately available.

9. Queue, Job, and Cron Hardening

Workers move money, send notifications, and call partner APIs with the same credentials as the web tier, usually with less scrutiny.

Pass IDs into jobs and reload the model instead of serializing sensitive attributes. If a job must carry a secret, implement ShouldBeEncrypted so the payload is encrypted at rest.
Verify webhook signatures with hash_equals(), reject timestamps older than a few minutes, and make the handler idempotent on the provider’s event ID with a unique index. Providers retry; your handler must not double-credit.
Set $tries and $backoff, implement failed(), and watch failed_jobs. Retrying a payment job blindly after a fix is how refunds go out twice.
ShouldBeUnique or an idempotency key stored before the side effect for provisioning and money movement, so a duplicate dispatch is a no-op.

10. CI/CD Security Gates

If a check is optional in CI, it stops running the first week a deadline slips. Make these fail the build:

composer audit (and npm audit for frontend assets), failing on known advisories; see the Composer audit docs. Install with --no-dev in production so debugging packages never ship.
Larastan (PHPStan) at a level that flags unchecked nullables and untyped request data flowing into models.
A Laravel version that still receives security fixes; security support ends about two years after each major release.
A php artisan route:list diff each release, so forgotten debug routes and retired API versions are noticed before a scanner finds them.
The cross-user access tests from section 3, and a test that the login limiter actually fires.

11. Incident Response Readiness

Each procedure below is a few lines of code or a short runbook. Write them before launch so the first run is not during an incident.

Revocation: one user with $user->tokens()->delete(); everyone by truncating personal_access_tokens. Sanctum stores only SHA-256 hashes, so a leaked database does not expose usable tokens, but rotate anyway.
Key rotation: a new APP_KEY with the old one in APP_PREVIOUS_KEYS, then every third-party credential the leaked environment could have exposed.
Forced update: a minimum supported build served from an app-config endpoint, so a client-side vulnerability can be retired without waiting on users.
Severity levels with a named owner, log retention that survives the incident, and regulatory deadlines written down in advance (GDPR allows 72 hours to notify the supervisory authority).

Where to Start on a Live API

If the API is already in production and you have one week, do these in order. Each is a day or less:

Set a Sanctum expiration and schedule sanctum:prune-expired.
Grep controllers for ::findOrFail( and ::find( on user-owned models; scope or add a policy to each.
Grep for ->all() passed into create, update, or fill; replace with validated().
Add the login limiter and confirm APP_DEBUG and trusted proxies in production.
Add request-ID logging and the failed-login listener, then wire one alert.
Put composer audit in CI.

Workers, webhooks, and the incident runbook follow in the next sprint. If you want help with the work, see backend API development.

Sources

OWASP API Security Top 10 (2023)
OWASP Laravel Cheat Sheet
Laravel docs: Sanctum, Authorization, Validation, Mass assignment, Rate limiting

Originally published at puneetpal.dev.

UIKit to SwiftUI Migration: 2026 Playbook with Code

Puneetpal Arneja — Mon, 26 Oct 2026 13:28:10 +0000

Short answer: migrate UIKit to SwiftUI incrementally. Host new SwiftUI screens in UIHostingController inside your existing navigation, wrap the UIKit components you keep with UIViewRepresentable, move state into @Observable models, and convert leaf screens first. Keep routing in UIKit until a whole flow is SwiftUI, then move that flow to NavigationStack.

Most UIKit codebases I see in 2026 have years of business logic inside view controllers, a coordinator or two, and a handful of SwiftUI screens somebody added in a hurry. Everyone agrees new work goes in SwiftUI. The open question is how to move the rest without freezing delivery for two quarters. This playbook covers the phased model I use, the interop code that holds the two stacks together, the mistakes that show up at the boundary, and a per-screen checklist for your definition of done.

Why Migration Efforts Fail

The failures are rarely about SwiftUI itself. They come from how the two stacks are stitched together. The ones I see most often:

Two sources of truth: a view controller property mirrored into an ObservableObject, with a bug every time one side forgets to update the other.
A NavigationStack inside a hosting controller already pushed on a UINavigationController: two navigation bars, two back stacks.
Screen-view analytics that lived in viewDidAppear and silently stopped firing when the screen became a SwiftUI view.
Hosted views that push or present on their own, so the coordinator loses track and deep links break.
No flag back to the UIKit screen, so the first regression is a hotfix release instead of a config change.

Each is cheap to prevent with a rule set before the first screen moves, and expensive to fix after twenty screens have copied the pattern.

Should You Migrate from UIKit to SwiftUI at All?

Not every app needs it. Migration pays off when you are still building features on the UI layer, when UIKit boilerplate is slowing reviews and onboarding, or when you want widgets, Live Activities, or new platform surfaces that are SwiftUI-only. It pays off less in these cases:

The app is in maintenance mode and the UI rarely changes.
A screen depends on fine-grained UIKit behaviour, such as complex compositional collection view layouts, custom transitions, or TextKit-based editing. Keep those in UIKit and wrap them.
A critical launch leaves no room for the team’s SwiftUI learning curve.
Your user base forces a minimum iOS version where the APIs you need do not exist yet.

A hybrid app that keeps some UIKit indefinitely is a perfectly good end state.

Minimum iOS version trade-offs

Deployment target	What you get	What you work around
iOS 15	`.task` with async/await, `ObservableObject`, `List` refresh and search	Only `NavigationView`, so keep navigation in UIKit
iOS 16	`NavigationStack`, `UIHostingConfiguration` for cells, hosting controller `sizingOptions`	Still `ObservableObject` and `@Published` for state
iOS 17+	`@Observable` and `@Bindable`, finer-grained view updates	Fewest workarounds; my recommended floor in 2026

Phase 1: Baseline and Readiness (2-3 Weeks)

Before you convert a single screen, record where the app stands so you can tell later whether the migration helped or hurt. Pull these from tools you already have:

Crash-free sessions per feature area, and launch time percentiles from the Xcode Organizer or MXAppLaunchMetric.
Time-to-interactive for the three or four highest-traffic screens, measured with os_signpost intervals so you can compare later.
Open UI defects per module, so you know which screens are already fragile.
A list of every UIViewController subclass with its parent, children, and what it presents. A short script over the source tree does this; it becomes the migration inventory.

Classify each screen in the inventory by how hard it will be to move:

Low: read-only detail screens and simple forms with no child controllers.
Medium: moderate state, validation, one or two embedded components.
High: custom collection view layouts, interactive transitions, text editing, or anything that owns child view controllers that have not been migrated.

Start with low and medium screens. The point of the first wave is to produce a pattern the rest of the team can copy, not to move the most code.

Phase 2: How Do UIKit and SwiftUI Work Together in One App?

The migration succeeds or fails at the boundary between old and new UI stacks. Apple gives you two directions of interop, and you will use both:

SwiftUI inside UIKit: UIHostingController for whole screens and child views, UIHostingConfiguration for table and collection view cells.
UIKit inside SwiftUI: UIViewRepresentable for views and UIViewControllerRepresentable for view controllers you are not ready to replace.

Push a SwiftUI screen from UIKit

This is the workhorse of an incremental migration. The UIKit navigation controller and coordinator stay in charge; only the screen content changes. Set the title on the host rather than relying on .navigationTitle inside the view to bridge across; it is one less thing to debug.

let model = ProfileModel(service: profileService)
let host = UIHostingController(rootView: ProfileView(model: model))
host.title = "Profile"
navigationController?.pushViewController(host, animated: true)

Embed SwiftUI as a child of a UIKit screen

When only part of a screen is migrating, add the hosting controller as a child view controller so lifecycle and trait changes propagate correctly. Without sizingOptions the hosted view reports no intrinsic size and Auto Layout gives it zero height.

let host = UIHostingController(rootView: SummaryCard(model: model))
host.sizingOptions = .intrinsicContentSize   // iOS 16+
addChild(host)
host.view.translatesAutoresizingMaskIntoConstraints = false
containerView.addSubview(host.view)
NSLayoutConstraint.activate([
    host.view.topAnchor.constraint(equalTo: containerView.topAnchor),
    host.view.bottomAnchor.constraint(equalTo: containerView.bottomAnchor),
    host.view.leadingAnchor.constraint(equalTo: containerView.leadingAnchor),
    host.view.trailingAnchor.constraint(equalTo: containerView.trailingAnchor)
])
host.didMove(toParent: self)

Two hosting details worth knowing before they cost you an afternoon: a hosted view above a keyboard can pick up extra padding because the host applies the keyboard safe area, and on iOS 16.4 and later host.safeAreaRegions = [] turns that off; and SwiftUI environment values do not cross the host boundary, so inject dependencies into the rootView explicitly or with .environment() on it.

Render SwiftUI rows in an existing table or collection view

On iOS 16 and later you can migrate cells before you migrate the list that contains them. Self-sizing works, and the cell keeps its UIKit selection and swipe behaviour:

cell.contentConfiguration = UIHostingConfiguration {
    OrderRow(order: order)
}

Wrap a UIKit view you are keeping

For a legacy control that is not worth rewriting yet, such as a custom chart, wrap it with UIViewRepresentable. The coordinator turns delegate callbacks into closures. Keep updateUIView cheap and idempotent; SwiftUI calls it on every relevant state change.

struct LegacyChart: UIViewRepresentable {
    var points: [ChartPoint]
    var onSelect: (ChartPoint) -> Void

    func makeUIView(context: Context) -> ChartView {
        let view = ChartView()
        view.delegate = context.coordinator
        return view
    }

    func updateUIView(_ view: ChartView, context: Context) {
        context.coordinator.onSelect = onSelect
        view.setPoints(points)
    }

    func makeCoordinator() -> Coordinator {
        Coordinator(onSelect: onSelect)
    }

    final class Coordinator: NSObject, ChartViewDelegate {
        var onSelect: (ChartPoint) -> Void
        init(onSelect: @escaping (ChartPoint) -> Void) { self.onSelect = onSelect }

        func chartView(_ view: ChartView, didSelect point: ChartPoint) {
            onSelect(point)
        }
    }
}

Bridge rules I enforce on every migration:

Every representable wrapper gets a ticket for its planned retirement, or a note saying it stays.
One observable model per feature boundary, owned by whoever creates the screen.
The same dependency container serves UIKit and SwiftUI modules; no second injection scheme.
Hosted SwiftUI views never push or present directly; they call back to the coordinator.

The same feature-boundary discipline is what lets one codebase serve several products. For a worked example, see how a white-label iOS app ships one Swift codebase as many branded apps.

Phase 3: Incremental Screen-by-Screen Migration

Move feature-by-feature, not file-by-file. A feature migration unit should include view, interactions, analytics events, error states, and accessibility checks. The safest unit is a leaf screen: one with no child view controllers, so it can be rebuilt in SwiftUI and swapped in behind a UIHostingController without touching anything around it.

Recommended order:

Read-only detail views
Settings and profile surfaces
Simple forms with straightforward validation
Reusable cells and components inside UIKit lists
High-traffic flows after pattern stability is proven

Keep a short scorecard per sprint: screens migrated, defects introduced in them, and whether feature lead time moved. If defects grow faster than screens for two sprints, stop and fix the pattern.

How Should State Management Map from UIKit to SwiftUI?

Pick one state strategy and enforce it. In practice that means a feature model per screen that holds state and logic, with views treated as rendering plus user intent. The model does not know whether it is being shown by a view controller or a SwiftUI view.

UIKit concept to SwiftUI equivalent

UIKit	SwiftUI
View controller holding state and logic	`@Observable` model (iOS 17+) or `ObservableObject` (iOS 13-16)
Owning a model in `viewDidLoad`	`@State` for an `@Observable` model, `@StateObject` for `ObservableObject`
Passing a shared service down the controller tree	`.environment(model)` on the root view and `@Environment(Model.self)` where it is read
Target-action and delegates	Closures and model methods; `@Bindable` for two-way edits
KVO and NotificationCenter for UI refresh	Observation tracking; `.onReceive` for remaining publishers
`UITableView` / `UICollectionView`	`List` or `LazyVStack`, or `UIHostingConfiguration` cells first
`UINavigationController` push	`NavigationStack` with `navigationDestination(for:)` (iOS 16+)

A model that works the same whether the screen is hosted from UIKit or lives in a pure SwiftUI flow:

import Observation
import SwiftUI

@MainActor
@Observable
final class ProfileModel {
    var name = ""
    var isSaving = false
    var errorMessage: String?

    private let service: ProfileService
    init(service: ProfileService) { self.service = service }

    func save() async {
        isSaving = true
        defer { isSaving = false }
        do {
            try await service.update(name: name)
        } catch {
            errorMessage = error.localizedDescription
        }
    }
}

struct ProfileView: View {
    @Bindable var model: ProfileModel

    var body: some View {
        Form {
            TextField("Name", text: $model.name)
            Button("Save") { Task { await model.save() } }
                .disabled(model.isSaving)
        }
    }
}

The same model can drive a UIKit screen that has not migrated yet. On iOS 17 you observe it with withObservationTracking(_:onChange:); on iOS 26 UIKit tracks @Observable reads in viewWillLayoutSubviews and updateProperties() automatically, and the UIObservationTrackingEnabled Info.plist key enables that back to iOS 18. Either way the view controller stops owning state, which is exactly the shape that makes replacing it trivial.

Keep domain and networking layers UI-agnostic so both stacks call the same code.
No business logic in views, no view code in models. The compiler will not stop you; review has to.
Load with .task rather than onAppear plus a detached Task; it cancels when the view disappears, so you do not update a model nobody is looking at.

How Do You Migrate Navigation to NavigationStack?

Navigation is often the hardest part because UIKit and SwiftUI have different mental models. My recommendation is two stages.

Stage one: UIKit keeps routing. Hosted SwiftUI screens expose closures, and the existing coordinator decides where to go. Do not put a NavigationStack inside a hosting controller that is already pushed onto a UINavigationController; you get two navigation bars and two back stacks.

struct OrderListView: View {
    let orders: [Order]
    var onSelect: (Order) -> Void

    var body: some View {
        List(orders) { order in
            Button(order.title) { onSelect(order) }
        }
    }
}

// In the UIKit coordinator
let list = OrderListView(orders: orders) { [weak self] order in
    self?.showDetail(for: order)
}
navigationController.pushViewController(UIHostingController(rootView: list), animated: true)

Stage two: a whole flow moves to SwiftUI. Once every screen in a tab or flow is SwiftUI, replace that flow’s navigation controller with a NavigationStack driven by a typed path. Deep links become an array of routes you assign to the path. Attach navigationDestination(for:) once, to the root content, not inside a lazy container; a destination declared inside a List row is registered late and the push can fail silently.

enum Route: Hashable {
    case order(Order.ID)
    case settings
}

struct OrdersFlow: View {
    @State private var path: [Route] = []

    var body: some View {
        NavigationStack(path: $path) {
            OrdersHome(open: { path.append($0) })
                .navigationDestination(for: Route.self) { route in
                    switch route {
                    case .order(let id): OrderDetailView(id: id)
                    case .settings: SettingsView()
                    }
                }
        }
    }
}

Rules for both stages:

Top-level routing stays in one place, even if that place is a UIKit coordinator for another year.
Deep-link parsing produces route values, never views or view controllers, so both stacks can consume them.
No ad-hoc push logic inside feature modules, in either stack.
Log route transitions from the router, so analytics do not depend on which stack rendered the screen.

How Do You Test a UIKit to SwiftUI Migration?

Moving logic into models is what makes the new screens testable without a UI harness. A model test runs in milliseconds and does not care which stack renders the result:

import Testing

@MainActor
@Test func saveClearsSavingFlag() async {
    let model = ProfileModel(service: MockProfileService())
    model.name = "Ada"
    await model.save()
    #expect(model.isSaving == false)
    #expect(model.errorMessage == nil)
}

For visual parity, preview the old and new screens side by side. Since Xcode 15 the #Preview macro accepts UIKit view controllers as well as SwiftUI views:

#Preview("UIKit checkout") {
    UINavigationController(rootViewController: CheckoutViewController(model: .preview))
}

#Preview("SwiftUI checkout") {
    CheckoutView(model: .preview)
}

Then set release gates per migrated screen:

Snapshot tests for high-traffic screens, recorded from the UIKit version before it is replaced.
Unit tests for the model, covering the error and empty states the old view controller handled.
UI automation for anything that touches money or identity.
A feature flag back to the UIKit screen, kept for at least one full release.
A phased App Store release with crash and launch-time thresholds checked each day.

Write the rollback rule down before release, with a number in it. For example: if crash-free sessions for the migrated module fall more than 0.2 percentage points below the Phase 1 baseline, flip the flag back. The exact threshold matters less than having one nobody has to negotiate at 11pm.

Accessibility and Design System Alignment

SwiftUI gets a lot of accessibility right by default, which makes the regressions it does introduce easy to miss. Check these on every migrated screen:

VoiceOver labels and reading order. Controls built from Image and Button need .accessibilityLabel; grouped rows usually want .accessibilityElement(children: .combine).
Dynamic Type at the largest sizes. Use semantic fonts and @ScaledMetric for spacing that was a fixed constant in UIKit.
Colour contrast through tokens shared by both stacks, so a UIColor asset and its Color counterpart cannot drift.
XCUIApplication.performAccessibilityAudit() (Xcode 15+) in the screen’s UI test, which catches missing labels and clipped text.

Share one component library across the coexistence period. A button that looks different depending on which stack rendered it is the kind of inconsistency users notice and nobody files a bug for.

How Long Does a UIKit to SwiftUI Migration Take?

These are the planning ranges I start from; codebase shape, team familiarity with SwiftUI, and how much feature work continues in parallel move them in either direction.

Light modernization: 6-10 weeks to move a handful of key screens and establish the pattern.
Mid-size migration: 3-5 months for core flows plus a shared component system.
Large enterprise migration: 6-12 months, phased by domain, with UIKit remaining in places.

The number that matters at the end is whether the screens you touched now ship faster with fewer defects than they did in Phase 1, not the percentage of SwiftUI.

What to Measure After Migration Starts

Feature lead time for migrated modules versus the Phase 1 baseline
Crash-free sessions and launch time for migrated modules, from the same sources as Phase 1
UI defects found in QA per migrated screen
How often the rollback flag was actually used

If those are not improving after the first wave, the pattern is wrong. Fix it before widening scope.

UIKit to SwiftUI Migration Checklist (Per Screen)

Put this into the definition of done for every migrated screen:

The screen is a leaf, or its child view controllers are already migrated or wrapped.
Business logic has moved out of the view controller into a model with unit tests.
The SwiftUI view is hosted with UIHostingController, and navigation still goes through the coordinator.
Analytics events fire with the same names and parameters as the UIKit version.
Loading, empty, and error states match or improve on the old screen.
Dynamic Type, VoiceOver labels and order, and dark mode are checked.
Old and new screens are compared in previews or snapshot tests.
A feature flag can route back to the UIKit screen for one release.
Crash-free rate and screen performance are watched against the Phase 1 baseline after release.
The UIKit screen and its flag are deleted once the new screen is stable.

90-Day Migration Execution Checklist

If you want the phases above as a calendar, this is the sequence I use for a team that has to keep shipping while it migrates:

Days 1-15: Baseline metrics, screen inventory, written bridge rules, and a named owner per feature area.
Days 16-30: Hosting and routing helpers, the model template, the rollback flag mechanism, and one reference screen that uses all of them.
Days 31-50: Low-risk screens, analytics parity checks, and the first adjustments to the review checklist.
Days 51-70: Medium-complexity flows with snapshot tests and a phased release.
Days 71-90: One high-value module, a regression review against the baseline, and updated architecture docs.

The pacing is deliberately slow at the start. Plans that front-load screen count produce QA debt that surfaces two or three releases later. A team already carrying incident load should start with fewer modules and stricter gates.

Where to Start

Pick one leaf screen, move its logic into a model, host the SwiftUI version behind a flag, and ship it. Everything else in this playbook is about making that step repeatable.

If you need hands-on help, I support both complete iOS app development and focused SwiftUI development and UIKit migration. If you want an outside read on the codebase before committing, start with a mobile architecture audit.

Sources

Originally published at puneetpal.dev.

Laravel Sanctum vs Passport for Mobile Apps (2026)

Puneetpal Arneja — Sat, 24 Oct 2026 01:57:12 +0000

For a mobile app that talks to its own Laravel API, use Sanctum. It issues one revocable token per device from a login endpoint you control, supports abilities and expiry, and has nothing to configure beyond a trait. Passport is a full OAuth2 server, and the only mobile cases that need one are apps you do not own asking for access to your users’ data, or other servers authenticating as themselves.

That is the short answer, and it matches what the Laravel docs say. The rest of this article is the reasoning, the parts of each package that matter once the app is in production, and the code for the places where Sanctum’s simplicity leaves a gap. It is one part of a larger guide to Laravel as a backend for mobile apps, which covers versioning, response shape, pagination, and push alongside authentication.

What Sanctum Actually Is

Sanctum is two separate features in one package, and only one of them applies to a native app.

API tokens. Modelled on GitHub personal access tokens. createToken() on the user writes a row to personal_access_tokens with a SHA-256 hash of a random string and returns the plain text once. The client sends it as a Bearer header and Sanctum looks the hash up on every request. Tokens can carry abilities, which work like scopes, and an optional expiry.
SPA cookie authentication. No tokens at all. A browser frontend on the same top-level domain logs in through the normal web guard and Sanctum lets the session cookie authenticate API routes, with CSRF protection intact. The statefulApi() middleware decides which origins get this treatment.

A mobile app uses the first feature only. There is no browser, no cookie jar worth trusting, and no CSRF problem, so the cookie half of Sanctum does not apply. The docs are explicit that API tokens are for mobile apps and third parties while first-party SPAs should use the cookie flow; the mistake worth avoiding is doing it the other way round.

What Passport Actually Is

Passport is a complete OAuth2 authorization server built on league/oauth2-server. It registers the /oauth/authorize and /oauth/token endpoints, stores clients and their redirect URIs, issues RSA-signed JWT access tokens together with refresh tokens, and implements the standard grants: authorization code (with or without PKCE), client credentials, device authorization, and the older password and implicit grants, which are off unless you turn them on.

The important word is server. Passport exists so that other applications can obtain access to your API on a user’s behalf, with the user approving a scope list on a consent screen you render. When the only client is your own app, every one of those moving parts is still present and still has to be configured, deployed, and kept secure, but none of them is doing anything you need.

Why Mobile Apps Almost Always Want Sanctum

Your own iOS or Android app is a first-party client. The user types their credentials into a screen you built, so there is no delegation to model and no third party to keep at arm’s length. What the app needs from the token system is narrower than OAuth2 and more specific:

One token per installed device, named so the user can recognise it in a sessions list.
The ability to revoke one device without logging out the others, and all of them at once on a password reset.
A token that survives app restarts for weeks, not minutes, because re-login on a phone costs you users.
Optionally, a token that can do less than the user can, so a stolen token from a read-only screen cannot place orders.

Sanctum covers each of these with a line or two. The login endpoint below follows the shape in the docs, with an expiry and abilities added, and device_name supplied by the app from the device model or a user-chosen label.

<?php
// routes/api.php
Route::post('/auth/login', function (Request $request) {
    $request->validate([
        'email' => ['required', 'email'],
        'password' => ['required'],
        'device_name' => ['required', 'string', 'max:100'],
    ]);

    $user = User::where('email', $request->email)->first();

    if (! $user || ! Hash::check($request->password, $user->password)) {
        throw ValidationException::withMessages([
            'email' => ['The provided credentials are incorrect.'],
        ]);
    }

    $expiresAt = now()->addDays(30);

    $token = $user->createToken(
        $request->device_name,
        ['orders:read', 'orders:write', 'profile:read'],
        $expiresAt,
    );

    return response()->json([
        'token' => $token->plainTextToken,
        'expires_at' => $expiresAt->toIso8601String(),
    ]);
})->middleware('throttle:login');

Returning expires_at alongside the token is a small addition that pays for itself later: the app can decide when to rotate without parsing anything, and support can see at a glance why a device was signed out.

Abilities are enforced on routes with the two middleware Sanctum ships, Laravel\Sanctum\Http\Middleware\CheckAbilities and CheckForAnyAbility. They are not aliased by default in Laravel 11 and 12, so register them once in bootstrap/app.php.

<?php
// bootstrap/app.php, inside withMiddleware()
$middleware->alias([
    'abilities' => CheckAbilities::class,  // token must have every listed ability
    'ability' => CheckForAnyAbility::class, // token must have at least one
]);

// routes/api.php
Route::get('/orders', [OrderController::class, 'index'])
    ->middleware(['auth:sanctum', 'abilities:orders:read']);

Route::post('/orders', [OrderController::class, 'store'])
    ->middleware(['auth:sanctum', 'abilities:orders:write']);

// Inside a policy, combine the token check with ownership
return $user->id === $order->user_id && $user->tokenCan('orders:write');

Revocation is a delete. Logout removes the current device’s row; a password reset, email change, or “sign out everywhere” removes them all. Because only hashes are stored, a leaked database does not yield usable tokens, though you should still rotate after an incident.

<?php
// Logout: only this device
Route::post('/auth/logout', function (Request $request) {
    $request->user()->currentAccessToken()->delete();

    return response()->noContent();
})->middleware('auth:sanctum');

// Password reset listener: every device, then the user logs in again
class RevokeTokensOnPasswordReset
{
    public function handle(PasswordReset $event): void
    {
        $event->user->tokens()->delete();
    }
}

// A sessions screen: revoke one named device the user picked
$request->user()->tokens()->where('id', $request->integer('token_id'))->delete();

What You Give Up: Refresh Tokens and Rotation

Sanctum has no refresh tokens. A token is valid until it expires or is deleted, and the default is that it never expires, because expiration in config/sanctum.php is null. That default is fine for a developer’s personal access token and wrong for a phone that can be lost, so the first production decision is to set it.

<?php
// config/sanctum.php: minutes, applies to every token without its own expiry
return [
    'expiration' => 60 * 24 * 30,
];

// routes/console.php: expired rows stay in the table until this runs
Schedule::command('sanctum:prune-expired --hours=24')->daily();

Once tokens expire you need an answer to “what happens on day 31?” Forcing a re-login is acceptable for some products and a churn problem for others. The alternative is rotation: an authenticated endpoint that issues a replacement with the same name and abilities and deletes the token that called it, in one transaction so a crash between the two statements cannot leave the user with zero tokens or two.

<?php
Route::post('/auth/token/rotate', function (Request $request) {
    $user = $request->user();
    $current = $user->currentAccessToken();
    $expiresAt = now()->addDays(30);

    $fresh = DB::transaction(function () use ($user, $current, $expiresAt) {
        $token = $user->createToken($current->name, $current->abilities, $expiresAt);
        $current->delete();

        return $token;
    });

    return response()->json([
        'token' => $fresh->plainTextToken,
        'expires_at' => $expiresAt->toIso8601String(),
    ]);
})->middleware(['auth:sanctum', 'throttle:rotate']);

On the client, call it when expires_at is within a few days, on app foreground, and store the new token before discarding the old one. Two details keep this honest. The endpoint requires a valid token, so an expired token cannot be refreshed; that is the trade-off versus an OAuth2 refresh token, which outlives the access token by design. And the endpoint needs its own rate limiter, because a captured token can otherwise be renewed forever by whoever holds it. If a long-lived credential that survives access token expiry is a hard requirement, that is a genuine reason to look at Passport.

When Passport Is the Right Choice

Three situations call for a real OAuth2 server, and they are about who the client is rather than how large the app is.

Apps you do not own. A partner’s app, a customer’s integration, or a public developer platform where someone else’s code asks for access to your users’ accounts. The user has to see what is being requested and approve it, and the client must never see the user’s password. That is the authorization code grant with PKCE.
Machine-to-machine. A reporting job, a warehouse system, or another one of your services calling the API as itself rather than as a user. That is the client credentials grant.
Real refresh semantics. A short-lived access token plus a longer-lived refresh token, with both lifetimes set centrally and refresh tokens revocable on their own.

Setup starts with php artisan install:api --passport, then passport:keys on each environment to generate the RSA key pair that signs tokens. The user model takes Passport’s HasApiTokens trait and the OAuthenticatable interface, and the api guard in config/auth.php switches to the passport driver. Scopes and lifetimes live in a service provider.

<?php
// app/Providers/AppServiceProvider.php
class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Passport::tokensCan([
            'orders:read' => 'Read your order history',
            'orders:write' => 'Place orders on your behalf',
            'profile:read' => 'Read your profile',
        ]);

        Passport::defaultScopes(['profile:read']);

        Passport::tokensExpireIn(CarbonInterval::hours(1));
        Passport::refreshTokensExpireIn(CarbonInterval::days(30));
        Passport::personalAccessTokensExpireIn(CarbonInterval::months(6));

        // Opt-in only, and the docs no longer recommend it. Leave it out
        // for a first-party mobile app; use Sanctum for that instead.
        // Passport::enablePasswordGrant();
    }
}

For a mobile app that belongs to someone else, create a public client, which has no secret, since a secret compiled into an app binary is not a secret. The app opens the authorization URL in a system browser sheet (ASWebAuthenticationSession on iOS, Custom Tabs on Android), receives the code on its redirect URI, and exchanges it together with the code verifier.

<?php
// Create the PKCE client once; Passport prints its client ID
// php artisan passport:client --public

// The mobile client builds the challenge from a random 43-128 char verifier
$codeVerifier = Str::random(128);
$codeChallenge = strtr(rtrim(base64_encode(hash('sha256', $codeVerifier, true)), '='), '+/', '-_');

// Step 1: open in the system browser
$authorizeUrl = 'https://api.example.com/oauth/authorize?'.http_build_query([
    'client_id' => $clientId,
    'redirect_uri' => 'com.partner.app://oauth/callback',
    'response_type' => 'code',
    'scope' => 'orders:read profile:read',
    'state' => $state,
    'code_challenge' => $codeChallenge,
    'code_challenge_method' => 'S256',
]);

// Step 2: exchange the code; no client_secret for a public client
$response = Http::asForm()->post('https://api.example.com/oauth/token', [
    'grant_type' => 'authorization_code',
    'client_id' => $clientId,
    'redirect_uri' => 'com.partner.app://oauth/callback',
    'code_verifier' => $codeVerifier,
    'code' => $code,
]);

// Protect routes by scope with auth:api and the scope middleware
Route::get('/orders', [OrderController::class, 'index'])
    ->middleware(['auth:api', CheckToken::using('orders:read')]);

// Machine-to-machine routes use the client as the resource owner instead
Route::get('/reports/daily', DailyReportController::class)
    ->middleware(EnsureClientIsResourceOwner::using('reports:read'));

Passport does not ship a mobile SDK, and the challenge and exchange above would normally run in Swift or Kotlin; the PHP form is here because it is the same algorithm and lints. The server side is the routes Passport registers plus the consent view you provide through Passport::authorizationView().

Passport Costs You Should Price In

Token size. Access tokens are RSA-signed JWTs that encode the client, user, scopes, and expiry, and come out around a kilobyte. A Sanctum token is the row ID, a pipe, and a 40-character random string. Per request that is noise; across a screen that fires a dozen calls on a cellular connection it is measurable, and it is the kind of thing that shows up when you profile a slow list.
Key management. passport:keys writes a private and public key to storage/. They must not be in git, every server that validates tokens needs the public key, and rotating the pair invalidates every token signed by the old one. Most teams load them from PASSPORT_PRIVATE_KEY and PASSPORT_PUBLIC_KEY environment variables, or point Passport::loadKeysFrom() at a mounted secrets path.
Revocation sets a flag rather than deleting the row. Expiry is encoded inside the signed token, so the expires_at column is informational and cannot be edited to shorten a token. To cut one off you call $token->revoke(), and separately $token->refreshToken?->revoke(), otherwise the client simply refreshes. Revoked and expired rows accumulate until passport:purge runs, so schedule it.
More tables, more grants, more surface. Five tables instead of one, a consent screen to design, redirect URI validation to get right, and the discouraged password and implicit grants sitting one method call away from being enabled by a well-meaning teammate.

<?php
// Revoke one connection, access and refresh token together
$token = Passport::token()->find($tokenId);
$token->revoke();
$token->refreshToken?->revoke();

// Password reset: every token the user has issued to any client
$user->tokens()->each(function (Token $token) {
    $token->revoke();
    $token->refreshToken?->revoke();
});

// routes/console.php
Schedule::command('passport:purge')->hourly();

Decision Table

Concern	Sanctum	Passport
Client you own (iOS, Android, Flutter)	Yes, the intended use	Works, but over-built
Third-party apps with user consent	No	Authorization code + PKCE
Machine-to-machine	Long-lived token on a service user	Client credentials grant
Token format	Opaque id\|random, hash stored	RSA-signed JWT, about 1 KB
Refresh tokens	None; rotate with a custom endpoint	Built in, separate lifetime
Scopes	Abilities per token	Scopes declared with tokensCan()
Expiry	Config minutes or per-token date; null by default	tokensExpireIn(); one year by default
Revocation	Delete the row	revoke() token and refresh token
Secrets to manage	None beyond APP_KEY	RSA key pair per environment
Database	One table	Clients, codes, tokens, refresh tokens, device codes
Housekeeping	sanctum:prune-expired	passport:purge

Migrating Between Them

The constraint that shapes every mobile migration applies here too: installed app builds keep using whatever token they were issued, for as long as users keep them. You cannot swap the guard on a Tuesday. Plan for a window where both guards accept requests.

Passport to Sanctum is the common direction, usually when a team discovers it adopted OAuth2 for one client it owns. Install Sanctum and add a second guard (sanctum is already a driver), publish a new login endpoint that issues Sanctum tokens, and ship an app build that uses it. Existing builds keep calling the Passport routes until their tokens expire; shorten tokensExpireIn() ahead of the switch so that window is weeks rather than a year. Protect shared routes with auth:sanctum,api so either guard can authenticate during the overlap. Once your build adoption analytics show the old builds are gone, remove the Passport guard, its routes, and the tables.

Sanctum to Passport happens when a partner programme arrives. The snag is that both packages ship a trait called HasApiTokens with the same method names, so one User model cannot simply use both. The cleanest path is to move the first-party app onto Passport as well, either through the PKCE flow in a system browser sheet or through Passport’s own createToken() for personal access tokens, which has a similar signature but mints a JWT. The same overlap window applies, with the Sanctum guard kept alive until old builds have gone. If the partner surface is small, it is worth asking first whether a separate, narrowly scoped Passport resource server in front of the same database would cost less than migrating your own app.

Either way, the migration is mostly a guard switch plus patience. The code that changes is the login endpoint, the route middleware, and the token-revocation paths listed above; business logic should not know which package authenticated the request.

Sources

Where This Fits

Pick Sanctum, set an expiry, add the rotation endpoint, and spend the time you saved on the controls that fail security reviews more often than the token library does: ownership checks on every lookup, rate limits on login, and logs that can answer who read what. Those are worked through in the Laravel API security checklist. If you would rather have someone build the auth layer and the API around it, see backend API development.

Originally published at puneetpal.dev.

How Long Does It Take to Build an iOS App? (2026 Timeline)

Puneetpal Arneja — Sat, 24 Oct 2026 01:57:06 +0000

Short answer: building an iOS app takes about 3 to 5 weeks for a TestFlight prototype, 4 to 8 weeks for a store-ready MVP, 4 to 8 months for a production app with payments and offline support, and 8 months or more for complex or regulated apps. Those ranges run from kickoff to App Store availability, review included.

Timelines slip for consistent reasons, and almost none of them are engineering speed. The schedule is usually lost in the weeks before development starts and the weeks after feature work “finishes”, two phases that rarely appear on the plan at all. Here is where the time goes, with ranges you can plan against.

Timeline and budget move together, so this pairs with what an iOS app costs, which uses the same tiers. If the ranges below look longer than you have, the lever is scope rather than staffing, which is what the MVP playbook is about.

iPhone App Development Timeline at a Glance

Kickoff to App Store availability, assuming a dedicated team and decisions made promptly.

App type	Timeline	Team	What’s included
Prototype	3-5 weeks	One developer	One workflow, mock data, TestFlight only
MVP	4-8 weeks	One developer, part-time design	Auth, a backend, one core workflow built properly, analytics, store launch
Production app	4-8 months	One to two developers, design, QA	Several workflows, payments, push, offline behaviour, a test suite, a real release process
Complex or regulated	8+ months	Three or more, plus security and backend	Compliance review, security assessment, and approval gates outside your control

The most common planning error is quoting the MVP range for a production app. The features look similar on a list; the difference is everything that makes an app supportable. If you are unsure which row you are in, MVP vs full build walks through that decision.

Budget follows the same rows. In the cost guide an MVP runs $15K-$40K. The production row splits in two: a standard app at $40K-$80K over 4-6 months, and a complex app at $80K-$150K over 6-8 months. Complex or regulated work starts at $150K. All of those assume US rates.

What Are the Phases of iOS App Development?

For an MVP at the top of its range, eight weeks from kickoff to the App Store, the split is roughly:

Discovery and scoping: 1 week. Which single workflow ships, what the API contract looks like, what is explicitly out. Skipping it moves the time into development, where it is more expensive.
Design: 1-2 weeks, overlapping development once the first flows are settled. Standard iOS components keep this short.
Core development: 3-4 weeks. The part everyone estimates, and the part least likely to be the problem.
Integration and hardening: 1-2 weeks. Real data, real devices, slow networks, and the edge cases the happy path hid.
Store preparation and review: 1 week. Screenshots, privacy declarations, a demo account for the reviewer, submission, and one likely rejection cycle.

A four-week MVP is the same five phases with one workflow, standard components, and a backend that already exists. Discovery and store preparation shrink to days rather than weeks; nothing is skipped.

A production app at six months, the middle of its range, stretches every phase rather than adding new ones: 2-3 weeks of discovery, 4-6 weeks of design overlapping development, 12-16 weeks of core development, 4-6 weeks of integration and hardening, and 1-2 weeks of store preparation and review. Design and development overlap, which is how 23-33 weeks of phase time fits a roughly 26-week calendar.

In both cases development is about half the calendar. Teams that compress by cutting discovery and hardening are removing the phases that prevent the overrun.

What Slows Down iOS App Development?

A backend being built in parallel is the single largest source of slippage. Mobile work stalls against unfinished or changing endpoints, and the delay is invisible until it is on the critical path. Contract-first API design, with the mobile team working against mocks, is the mitigation.

After that, in rough order of damage:

Design decided during development, where every unresolved screen becomes a blocking question mid-sprint.
Slow decisions. A team waiting two days for an answer loses more time than any technical problem will cost them.
Third-party dependencies such as payment providers, identity verification, and enterprise SSO, each of which runs on someone else’s timeline and approval.
The device and OS matrix, where older devices and the current beta both surface issues late if they are not tested continuously.

How Long Does App Store Review Take?

Review itself is fast in 2026, typically 24 to 48 hours. The cost is a rejection on a first submission, which commonly comes from:

Privacy manifest and tracking declarations not matching actual SDK behaviour
Missing in-app account deletion where an account can be created
Subscription terms and pricing not presented as required
Permission prompts without a clear justification string
Demo credentials that do not work for the reviewer

Each is avoidable and each costs a round trip of a few days. Plan one rejection cycle into a first launch and treat it as normal rather than as a failure.

Two other review steps catch teams out. External TestFlight testing needs its own beta review before outside testers can install a build, so the first external beta should not be scheduled for the day before a demo. And while Apple accepts expedited review requests for urgent cases such as a critical bug fix, that is a request rather than a guarantee, so it is not a planning tool. Apple documents the process and current guidance on its App Review page.

How Can You Build an iOS App Faster?

These work. Most other accelerations trade schedule for rework:

Cut scope, not phases. The only reliable lever. Fewer workflows built properly beats more workflows built thinly.
Finish design before the sprint that needs it. Not before the project; before the sprint.
Define the API contract first. Mobile and backend then proceed in parallel against mocks instead of sequentially against reality.
Put someone with authority in the standup. Decision latency is a schedule item.
Ship to TestFlight from week one. Release problems found in week two are cheap; found in week eleven they are the critical path.

What does not work: adding developers to a late project, running QA only at the end, and treating store submission as an afterthought.

How Do You Estimate Your Own App’s Timeline?

Work through these in order before trusting any single number, including the ones above:

Pick the row honestly. Count the workflows a user must complete on day one, not the features on the wish list. One workflow is an MVP; several, with payments and offline behaviour, is a production app.
Check the backend. If it does not exist yet or is changing, assume it is on the critical path and plan the API contract first.
Count the outside approvals. Payment providers, identity checks, enterprise SSO, and compliance sign-off each add a timeline you do not control.
Add the phases estimates leave out. Discovery, integration and hardening, store preparation, and one review rejection cycle.
Price it alongside the schedule. Time and budget move together; the iOS app cost breakdown uses the same tiers and shows the hours behind each one.

If the result is longer than you have, cut scope rather than phases. The mobile MVP playbook covers how to choose what stays. When you want a delivery plan built around your own constraints, that is part of my iOS app development work.

Originally published at puneetpal.dev.

Laravel API for Mobile Apps: Backend Design Guide (2026)

Puneetpal Arneja — Sat, 24 Oct 2026 01:57:00 +0000

Laravel works well as the backend for iOS, Android, Flutter, and React Native apps if the API is designed around one fact: you cannot force users to update. Version every route, return one predictable JSON shape, issue revocable per-device tokens, paginate with cursors, and ship a minimum-supported-build check in the first release.

A web frontend and its API deploy together, so a breaking change is fixed in one release. A mobile client is different. Once a build is approved and installed, it keeps calling your API exactly as it was compiled to, sometimes for years. Every decision below follows from that constraint. This guide covers the design side; for hardening the same API, pair it with the Laravel API security checklist.

Is Laravel a good backend for a mobile app?

For most product apps, yes. Laravel gives a mobile team authentication, queues, scheduled jobs, notifications, file storage, validation, and an ORM out of the box, so a small team can ship a complete API without assembling a framework from parts. It is a weaker fit for workloads dominated by long-lived connections or heavy computation.

Where it fits well:

Transactional product apps: accounts, orders, bookings, content feeds, subscriptions, admin workflows. This is the bulk of what mobile apps need from a server.
Small teams who want one conventional codebase that a new hire can read on day one.
Apps with background work (push notifications, upload processing, syncing with third-party systems), because queues and the scheduler are first-party.

Where I would look elsewhere, or add a separate service:

Real-time systems where WebSocket fan-out is the core product rather than a feature.
CPU-heavy pipelines such as media transcoding or model inference, which belong in dedicated workers.
Teams whose entire skill set is in another ecosystem. The best backend is one your team can operate at 2 a.m.

How should a Laravel API shape JSON for mobile clients?

Return every resource through an API Resource class and every error through one envelope. Mobile decoders are strict: Swift’s Codable and Kotlin serializers fail on unexpected types, so a field that is sometimes a string and sometimes null, or an error that is sometimes HTML, becomes a crash or a blank screen in production.

Laravel API Resources decouple the response from the database schema, which is exactly what an API serving old app builds needs. Rename a column and the resource keeps emitting the old key.

class OrderResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->public_id,          // never the auto-increment key
            'status' => $this->status->value,  // backed enum, stable strings
            'total' => [
                'amount' => $this->total_minor, // integer minor units, not floats
                'currency' => $this->currency,
            ],
            'updated_at' => $this->updated_at->toIso8601String(),
        ];
    }
}

Rules that keep decoders working across releases:

Only additive changes within a version. Adding a field is safe; removing, renaming, or changing a type is a new version.
Money as integer minor units with a currency code. Dates as ISO 8601 with an offset.
Enums as strings, and clients that map unknown values to a fallback case instead of failing the whole decode. Swift: give the enum a raw value and a custom init(from:) that falls back to .unknown.
JSON for every error, including 401, 404, 422, 429, and 500. A mobile client cannot do anything useful with an HTML error page.

Laravel decides whether to render an exception as JSON from the Accept header, and mobile HTTP clients do not always send one. Force it for API routes in bootstrap/app.php and render your envelope from the same place:

// bootstrap/app.php
return Application::configure(basePath: dirname(__DIR__))
    // ...routing and middleware...
    ->withExceptions(function (Exceptions $exceptions) {
        $exceptions->shouldRenderJsonWhen(fn (Request $request) => $request->is('api/*'));

        $exceptions->render(function (ApiException $e, Request $request) {
            return response()->json([
                'error' => [
                    'code' => $e->code(),          // stable, machine-readable
                    'message' => $e->getMessage(), // display text, safe to change server-side
                    'fields' => [],
                ],
            ], $e->status());
        });
    })->create();

The code is what the app branches on, so it never changes once shipped. The message is copy you can reword without a release. fields carries per-field validation messages for 422 responses and is otherwise empty, so the client always has one decoder and one error-handling path.

Which authentication should a mobile app use with Laravel?

For a first-party app, use Laravel Sanctum API tokens: one token per device, named after the device, scoped with abilities, and revocable by deleting a row. Reach for Passport only when you need an OAuth2 server for third-party clients. Self-contained JWTs make revocation harder than it needs to be.

Sanctum vs Passport vs JWT for mobile apps

Factor	Sanctum tokens	Passport (OAuth2)	JWT package
Token type	Opaque, stored hashed in the database	OAuth2 access and refresh tokens	Signed, self-contained token
Revoke one device	Delete the token row	Revoke the token and its refresh token	Needs a denylist until expiry
Refresh flow	Not built in; use expiry plus re-login or a custom rotate endpoint	Built in	Provided by the package
Third-party clients	Not designed for it	Yes, including authorization code with PKCE	Not designed for it
Setup and upkeep	Low, first-party	Higher: clients, grants, keys	Moderate, community-maintained
Best fit	Your own iOS, Android, Flutter, or React Native app	Platforms where partners need delegated access	Stateless verification across several services

Issue the token from a login endpoint that takes a device_name, so users can see and sign out individual devices, and a lost phone can be revoked without logging out everything else:

$token = $user->createToken(
    $request->input('device_name'),    // e.g. "iPhone 16 - iOS"
    ['orders:read', 'orders:write'],   // abilities checked per route
    now()->addDays(30),                // per-token expiry
);

return ['token' => $token->plainTextToken];

On both sides of the token lifecycle:

Store the token in the platform keystore: the iOS Keychain or Android Keystore-backed storage. Never in UserDefaults, plain shared preferences, or AsyncStorage.
Set an expiry. Sanctum tokens never expire unless expiration in config/sanctum.php is set (minutes) or createToken() gets a date. Pair it with a scheduled sanctum:prune-expired so the table does not grow forever.
Revoke on risk events. A password change, account recovery, or “sign out all devices” should delete the relevant token rows immediately.
Treat a 401 as a state, not an error. The client clears the stored token and returns to sign-in once, rather than retrying in a loop.

For the client side of the same problem, the mobile banking security checklist covers token storage, session handling, and the controls a security review expects in the app.

How do you version a Laravel API so old app builds keep working?

Put the version in the URL, starting at /api/v1 on day one, and only make additive changes inside a version. Every request carries the app’s version in headers, and a public policy endpoint tells each platform its minimum and recommended version, so you can prompt or force an update before you remove anything an old build depends on.

// routes/api.php
Route::get('/app/version-policy', VersionPolicyController::class);   // public, cacheable

Route::prefix('v1')->middleware('app.version')->group(function () {
    Route::post('/auth/token', [AuthController::class, 'store'])
        ->middleware('throttle:auth');

    Route::middleware(['auth:sanctum', 'throttle:api'])->group(function () {
        Route::get('/orders', [OrderController::class, 'index']);
        Route::delete('/auth/token', [AuthController::class, 'destroy']);
    });
});

The contract is small. The client sends X-App-Version (semver), X-App-Build and X-App-Platform (ios or android) on every request. GET /app/version-policy?platform=ios returns minimum, recommended, latest, store_url and an optional message. The app.version middleware answers any request from a version below minimum with 426 Upgrade Required and the same JSON, and adds Deprecation and Sunset headers below recommended. A Swift client using URLSession:

struct VersionPolicy: Decodable {
    let minimum: String
    let recommended: String
    let latest: String
    let storeUrl: URL
    let message: String?
}

func fetchVersionPolicy() async throws -> VersionPolicy {
    var components = URLComponents(string: "https://api.example.com/app/version-policy")!
    components.queryItems = [URLQueryItem(name: "platform", value: "ios")]
    var request = URLRequest(url: components.url!)
    let info = Bundle.main.infoDictionary
    request.setValue(info?["CFBundleShortVersionString"] as? String, forHTTPHeaderField: "X-App-Version")
    request.setValue(info?["CFBundleVersion"] as? String, forHTTPHeaderField: "X-App-Build")
    request.setValue("ios", forHTTPHeaderField: "X-App-Platform")

    let (data, response) = try await URLSession.shared.data(for: request)
    guard (response as? HTTPURLResponse)?.statusCode == 200 else {
        throw URLError(.badServerResponse)
    }

    let decoder = JSONDecoder()
    decoder.keyDecodingStrategy = .convertFromSnakeCase
    return try decoder.decode(VersionPolicy.self, from: data)
}

A deprecation policy that holds up:

Log X-App-Version on every request. You cannot retire a version without knowing which builds still call it.
Run versions side by side. v2 controllers reuse the same services and models; only the resources and request validation differ.
Soft prompt, then hard block. Raise recommended first, and only raise minimum once usage of the old version is negligible by your own numbers, not by the calendar.
Treat a 426 from any endpoint as “show the update screen”, so even a build that never fetched the policy shows something sensible.

Header-based versioning (Accept: application/vnd.example.v2+json) is tidier in theory. In practice a URL prefix is easier to grep in logs, route in a load balancer, and explain to the person writing the Android client.

How should pagination and sync work for offline-first apps?

Use cursor pagination for lists and an updated_since parameter for sync. Offset pagination skips or duplicates rows when data changes between page requests, which happens constantly on a phone with a flaky connection. Cursors are stable, and delta sync means the app downloads only what changed.

$orders = $request->user()->orders()
    ->withTrashed()   // include soft-deleted rows as tombstones
    ->when($request->filled('updated_since'), fn ($query) =>
        $query->where('updated_at', '>', $request->date('updated_since')))
    ->orderBy('updated_at')
    ->orderBy('id')   // tie-breaker: cursor columns must be unique together
    ->cursorPaginate(min($request->integer('per_page', 50), 100));

return OrderResource::collection($orders);

Details that decide whether sync is reliable:

Deletions must sync too. Soft deletes with a deleted_at in the resource let the client remove local rows it would otherwise keep forever.
The client stores the server’s timestamp, not the device clock, as its next updated_since value. Return it in the response; device clocks drift.
Writes are idempotent. Accept a client-generated UUID or Idempotency-Key header on create requests, store it with the row, and return the existing record on a repeat, so a retry after a dropped response does not create a duplicate.
Conflicts have a rule decided up front: last write wins, server wins, or a 409 with both versions that the app resolves. Undefined behaviour here turns into data loss.

How do you send push notifications from Laravel?

Send them from queued jobs, never inside the request. Store each device’s push token against the user and platform, dispatch a queued notification, and deliver through APNs for iOS and Firebase Cloud Messaging for Android. For APNs, use token-based authentication with a .p8 signing key rather than a certificate; the key does not expire and works across all your apps. For FCM, use the HTTP v1 API; the legacy API was shut down in 2024 and some older packages still target it.

Register tokens on every launch with an upsert endpoint. Push tokens change, and the app is the only party that knows when.
Prune invalid tokens when APNs returns 410 or FCM reports UNREGISTERED, otherwise the queue spends its time on devices that no longer exist.
Keep payloads small and non-sensitive. Send an identifier and let the app fetch the detail over the authenticated API; lock screens are not private.
Separate queues by priority so a bulk marketing send cannot delay a time-sensitive transactional alert.

How should mobile apps upload files to a Laravel backend?

Let the app upload directly to object storage with a short-lived presigned URL, then tell the API the upload finished. Streaming large photos or videos through PHP ties up workers on slow mobile connections. Laravel generates presigned S3 upload URLs, so the API only authorizes and records the file.

['url' => $url, 'headers' => $headers] = Storage::disk('s3')
    ->temporaryUploadUrl(
        'uploads/'.$request->user()->id.'/'.Str::uuid().'.jpg',
        now()->addMinutes(5)
    );

return ['upload_url' => $url, 'headers' => $headers];

A presigned PUT cannot enforce a size limit, so after the app confirms the upload, check the object server-side: Storage::size() against your cap, the real content type from the bytes rather than the extension, and that the key belongs to the caller. Push any processing such as thumbnails onto a queue. Never trust the file type the client claims.

What rate limits does a mobile API need?

At minimum, a general per-user limit for authenticated routes and much stricter limits on login, one-time codes, and password reset. Key limits by user ID when authenticated and by IP otherwise. Mobile carriers put many users behind shared IP addresses, so IP-only limits punish legitimate users.

Laravel’s named rate limiters express this in a few lines. The numbers below are starting points; tune them from your own traffic:

// AppServiceProvider::boot()
RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});

RateLimiter::for('auth', function (Request $request) {
    return [
        Limit::perMinute(5)->by(strtolower((string) $request->input('email')).'|'.$request->ip()),
        Limit::perMinute(20)->by($request->ip()),
    ];
});

The throttle middleware adds Retry-After and X-RateLimit-* headers to the 429 for you; make sure the body is still your error envelope, and make the client honour Retry-After with jittered backoff. A client that retries instantly on failure turns a brief incident into a self-inflicted outage. The OWASP API Security Top 10 lists unrestricted resource consumption and broken authorization among the most common API risks, and both apply directly to mobile backends.

What should you monitor on a mobile backend?

Error rates and latency per endpoint, broken down by app version and platform. A backend change that looks healthy overall can break one older build entirely, and you will only see it if requests carry the client build and your dashboards can filter by it.

Request context: client platform, build, and a request ID. Generate the ID in middleware, put it in Log::withContext(), and return it in a response header so support can match an app report to a server log.
Error tracking on both sides, with the same request ID visible in app crash reports and server exceptions.
Queue health: backlog depth, failed jobs, and job duration. Laravel Pulse or a hosted APM covers the basics; Horizon adds detail if you run Redis queues.
Version adoption: requests per build over time, which is the number you need before retiring an API version.

Where does Next.js fit next to a Laravel mobile backend?

Beside Laravel, not in front of the mobile app. Next.js works well for an admin dashboard, marketing site, or web version of the product, consuming the same Laravel API or a separate web backend-for-frontend (see Next.js web development). The mobile app should call Laravel directly through its versioned API.

Adding a Next.js layer between the app and Laravel means two services that must both stay compatible with every installed build. Keep the mobile contract in one place. If you are planning the stack as a whole, my Laravel API backend development service covers the API, admin tooling, and infrastructure together.

What should you build first?

Before the first app release, get the decisions that are expensive to reverse in place: the /api/v1 prefix, the response and error envelope, per-device Sanctum tokens with an expiry, the version-policy endpoint with a minimum version, and app version logging. Everything else in this guide can be added later without breaking installed apps. Cursor pagination is the one I would move up the list if the app has any list that grows, because switching from offset to cursor later changes the response shape.

If you are still scoping the product, the mobile MVP playbook covers what to include in a first release, and mobile app development covers the client side. When you want the backend designed and built alongside the app, I offer Laravel backend and API development for mobile apps.

Frequently Asked Questions

Should a mobile app use Laravel Sanctum or Passport?

Use Sanctum when your own first-party app is the only client. It issues revocable per-device tokens with very little setup. Choose Passport only when you need a real OAuth2 server, for example when third-party developers or partner apps must obtain delegated access to your users' data.

How long should a Laravel API keep supporting an old version?

Long enough that almost no active installs still depend on it. Set the window from your own analytics on build adoption rather than the calendar, announce it in-app before removal, and raise the minimum version in the version policy (old builds then get a 426 and an update screen) so the last stragglers see an update prompt instead of broken screens.

Can Laravel handle real-time features for a mobile app?

Yes. Laravel broadcasting with Laravel Reverb, or a hosted WebSocket service, covers live updates while the app is in the foreground. Push notifications through APNs and FCM still handle the background case, because mobile operating systems suspend open sockets when the app is not active.

Should a mobile app call Laravel directly or go through Next.js?

Call Laravel directly. A mobile client gains little from an extra hop, and every layer is another thing that has to stay backward compatible with old app builds. Next.js earns its place for the admin panel, marketing site, or a web client, not as a proxy in front of the mobile API.

Originally published at puneetpal.dev.