Authentication

Scope

Authentication is an Account-profile feature. Guest projects keep shared pages in the source for maintainability, but isGuestLocal prevents Account tokens, requests, and auth routes from being used.

Supported flows

The Flutter template includes:

• Email/password registration and login.
• Email verification and resend.
• Forgot-password and reset-password flows.
• Google sign-in and registration through google_sign_in.
• Connected Google and Apple account management in Settings.
• Logout, password change, active-session listing/revocation, login history, and account deletion.

Apple Sign in with Apple is used by the connected-account provider. The current login/register UI exposes Google as the social sign-in action; add a separate Apple login UI only when your backend/product flow is configured for it.

Token lifecycle

providers/auth_provider.dart stores the Laravel Sanctum bearer token through helpers/storage.dart (which uses secure storage for secrets). DioService injects Authorization: Bearer <token> and invokes the unauthorized handler on 401, clearing local auth and returning to Login.

The mobile app does not create JWTs. Laravel issues Sanctum personal access tokens; Go validates the same hashed token records and abilities.

Google setup

Register the final Android package/iOS bundle ID with Google/Firebase, provide the matching Firebase files/options, and configure the Google client IDs required by google_sign_in. Test on a native build, not only a desktop/web run.

Apple connected-account setup

providers/connected_accounts_provider.dart uses sign_in_with_apple to connect an Apple identity through /api/v1/auth/connected-accounts/apple. Configure the Apple capability, Service ID/keys, and backend credentials for the final bundle ID before testing.

API URL

Edit lib/config/app_env.dart:

static const String apiBaseUrl = String.fromEnvironment(
  'API_BASE_URL',
  defaultValue: 'http://10.0.2.2:8000',
);

Or keep the default and override at build time with flutter run --dart-define=API_BASE_URL=http://10.0.2.2:8000 (see docs/ENVIRONMENT.md). The client appends /api/v1 using Endpoints.buildApiPath. Do not include /api/v1 in the host root.

Security UI caveat

The security page provides working session listing/revocation, login history, password change, and account deletion. The Biometric Login and Two-Factor Authentication switches are currently presentation/state toggles; they do not activate a native biometric lock or server-side 2FA challenge by themselves.

Relevant files

• providers/auth_provider.dart
• providers/user_provider.dart
• providers/connected_accounts_provider.dart
• providers/security_provider.dart
• services/dio_service.dart
• helpers/storage.dart
• lib/main.dart and lib/bootstrap/account_bootstrap.dart for route/session guards