auth0-flutter-native

What this skill does

# Auth0 Flutter Native (iOS/Android) Integration

`auth0_flutter` is the official Auth0 SDK for Flutter applications. On **mobile (iOS/Android)**, it performs authentication through the device's system browser (Web Auth / Universal Login) and stores tokens securely in the platform keychain/keystore via the built-in `CredentialsManager`, with optional biometric protection.

> **Agent instruction:** Before providing SDK setup instructions, fetch the latest release version by running one of:
> ```bash
> gh api repos/auth0/auth0-flutter/releases/latest --jq '.tag_name'
> ```
> ```bash
> flutter pub info auth0_flutter 2>/dev/null | head -5
> ```
> Or check pub.dev:
> ```bash
> curl -s https://pub.dev/api/packages/auth0_flutter | python3 -c "import sys,json;print(json.load(sys.stdin)['latest']['version'])"
> ```
> Use the returned version in all dependency lines instead of any hardcoded version below. Current known version: `2.1.0`.

## When NOT to Use

- **Flutter web**: Use [auth0-flutter-web](/auth0-flutter-web) — web uses a different platform interface (`Auth0Web`) wrapping Auth0 SPA JS
- **Native iOS (Swift, no Flutter)**: Use [auth0-swift](/auth0-swift)
- **Native Android (Kotlin/Java, no Flutter)**: Use [auth0-android](/auth0-android)
- **React Native**: Use [auth0-react-native](/auth0-react-native)
- **React SPA**: Use [auth0-react](/auth0-react)
- **Node.js/Express servers**: Use [auth0-express](/auth0-express)

## Prerequisites

- **Flutter** 3.24.0+
- **Dart** 3.5.0+
- **Android**: minSdkVersion 21+, compileSdkVersion 34+
- **iOS**: 14.0+ (Universal Link callbacks require iOS 17.4+)
- Auth0 account — [Sign up free](https://auth0.com/signup)
- Auth0 CLI — [install instructions](https://github.com/auth0/auth0-cli) (used to create and configure the Auth0 application)

## Quick Start Workflow

> **Agent instruction:** Follow these steps in order. If you encounter an error at any step, attempt to fix it up to 5 times before calling `AskUserQuestion` to ask the user for guidance. Always search existing code first — if there are existing login/logout handlers, hook into them rather than creating new ones.

### Step 1 — Install SDK

> **Agent instruction:** Check the project directory for `pubspec.yaml`. If present, add the dependency. If not found, this is not a Flutter project — ask the user.
>
> Run in the project root:
> ```bash
> flutter pub add auth0_flutter
> ```
>
> Verify the dependency was added to `pubspec.yaml`:
> ```yaml
> dependencies:
>   auth0_flutter: ^2.1.0
> ```

### Step 2 — Configure Auth0

> **Note:** The Auth0 Domain and Client ID are **public configuration** (not secrets) — a native app uses PKCE with no client secret. Pass them directly to `Auth0(domain, clientId)`; there is no need to store them in environment variables or hide them.
>
> **Agent instruction:**
> - **If Auth0 credentials (domain AND client ID) are already in the user's prompt:** Use those values directly in the `Auth0(...)` constructor and proceed to Step 3.
> - **If no credentials are provided:** Ask the user which setup they prefer using `AskUserQuestion`: _"How would you like to set up the Auth0 application — automatic (I run the Auth0 CLI to create it) or manual (you create it in the Auth0 Dashboard and give me the Domain + Client ID)?"_
>   - **Automatic:** Follow the Auth0 CLI steps in the Setup Guide to create the Native application.
>   - **Manual:** Ask the user for their Auth0 Domain and Client ID and use them directly.
>
> Follow [Setup Guide — Auth0 Configuration](./references/setup.md#auth0-configuration) for the pre-flight checks and the `auth0 apps create` command.

### Step 3 — Configure Android

> **Agent instruction:** Edit `android/app/build.gradle` (or `build.gradle.kts`) and add `manifestPlaceholders` inside `android { defaultConfig { ... } }`. These supply the callback URL the SDK's `RedirectActivity` intent filter registers — without them the app will not build correctly for Auth0.

For `android/app/build.gradle` (Groovy):
```groovy
android {
    defaultConfig {
        manifestPlaceholders = [auth0Domain: "YOUR_AUTH0_DOMAIN", auth0Scheme: "https"]
    }
}
```

For `android/app/build.gradle.kts` (Kotlin DSL):
```kotlin
android {
    defaultConfig {
        manifestPlaceholders["auth0Domain"] = "YOUR_AUTH0_DOMAIN"
        manifestPlaceholders["auth0Scheme"] = "https"
    }
}
```

> **Agent instruction:** Use `auth0Scheme: "https"` to use Android App Links (recommended). If the app targets a custom scheme instead, set it to a lowercase scheme string and pass the same scheme to `webAuthentication(scheme: ...)` in Dart. See [Setup Guide](./references/setup.md) for details.

### Step 4 — Configure iOS

> **Agent instruction:** For the default HTTPS (Universal Link) flow on iOS 17.4+, no `Info.plist` change is required, but the **Associated Domains** capability must be added in Xcode (`webcredentials:YOUR_AUTH0_DOMAIN`). For older iOS or a custom URL scheme, add a `CFBundleURLTypes` entry to `ios/Runner/Info.plist`:

```xml
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>None</string>
    <key>CFBundleURLName</key>
    <string>auth0</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    </array>
  </dict>
</array>
```

### Step 5 — Configure Callback URLs

> **Agent instruction:** Register the platform-specific callback and logout URLs using the Auth0 CLI. Determine the Android package name (from `android/app/build.gradle` `applicationId`) and the iOS bundle identifier (from Xcode / `PRODUCT_BUNDLE_IDENTIFIER`), then run the command below, replacing the placeholders (`CLIENT_ID`, `YOUR_DOMAIN`, `ANDROID_PACKAGE_NAME`, `IOS_BUNDLE_ID`) with the project's values:
>
> ```bash
> auth0 apps update CLIENT_ID \
>   --callbacks "https://YOUR_DOMAIN/android/ANDROID_PACKAGE_NAME/callback,https://YOUR_DOMAIN/ios/IOS_BUNDLE_ID/callback" \
>   --logout-urls "https://YOUR_DOMAIN/android/ANDROID_PACKAGE_NAME/callback,https://YOUR_DOMAIN/ios/IOS_BUNDLE_ID/callback" \
>   --no-input
> ```

The callback URL formats are:
- **Android**: `https://YOUR_DOMAIN/android/YOUR_PACKAGE_NAME/callback`
- **iOS**: `https://YOUR_DOMAIN/ios/YOUR_BUNDLE_ID/callback`

### Step 6 — Implement Authentication

> **Agent instruction:** Search the project for the main app entry point (`main.dart`). Determine the state management approach:
> - Look for `provider`, `riverpod`, `bloc`, `GetX`, or `mobx` imports
> - If none found, use basic `StatefulWidget` with `setState`
>
> Then follow **only** the matching path below. If ambiguous, ask via `AskUserQuestion`: _"Which state management approach does your Flutter app use — Provider, Riverpod, Bloc, or basic setState?"_

#### Basic StatefulWidget (Default)

> **Agent instruction:** Create an `AuthService` class, then wire it into the app's root widget. Search for the `MaterialApp` or `CupertinoApp` widget and update accordingly. On startup, restore the session from the `CredentialsManager` cache.

```dart
// lib/auth_service.dart
import 'package:auth0_flutter/auth0_flutter.dart';

class AuthService {
  late final Auth0 _auth0;
  Credentials? _credentials;

  AuthService({required String domain, required String clientId}) {
    _auth0 = Auth0(domain, clientId);
  }

  bool get isAuthenticated => _credentials != null;
  UserProfile? get user => _credentials?.user;

  /// Restore a stored session on app startup, if one exists.
  Future<void> init() async {
    final hasValid = await _auth0.credentialsManager.hasValidCredentials();
    if (hasValid) {
      _credentials = await _auth0.credentialsManager.credentials();
    }
  }

  /// Launch Web Auth via the system browser. Tokens are stored automatically.
  Future<void> login() async {
    _credentials = await _auth0
        .webAuthentication()
        .login(scopes: {'openid', 'profile', 'email', 'offline_access'});
  }

  /// Clear the session in the browser and wipe stored credentials.
  Fut