> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thefaithapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flutter SDK Quickstart

> Add hosted member sign-in and authenticated v1 API requests to an Android or iOS Flutter app.

# Use the API from Flutter

The `thefaithapp_auth` package signs a member in through TheFaithApp and gives
your Flutter app an authenticated client for `v1` API requests. Your app does
not need to host a callback website.

## Before you begin

You need:

* a Flutter app targeting Android or iOS
* its Android application ID or iOS bundle ID
* a client API key from `Settings > Developer Access`

<Steps>
  <Step title="Add the package">
    Add the package to your `pubspec.yaml`:

    ```yaml theme={null}
    dependencies:
      thefaithapp_auth: ^0.1.0
    ```

    Install it:

    ```bash theme={null}
    flutter pub get
    ```

    Stop and rebuild the app after adding the package so Flutter can register
    its platform code.
  </Step>

  <Step title="Register your Flutter app">
    In the TheFaithApp dashboard:

    1. Open `Settings > Developer Access`.
    2. Click **Add Flutter app**.
    3. Append `.thefaithapp` to your application ID.
    4. Add the app and copy your client API key.

    For an application ID of `com.example.app`, enter:

    ```text theme={null}
    com.example.app.thefaithapp
    ```

    The dashboard creates the callback expected by the package:

    ```text theme={null}
    com.example.app.thefaithapp://auth/callback
    ```

    Use a lowercase reverse-domain application ID containing letters, numbers,
    and dots. Avoid underscores because they cannot be used in a callback URI
    scheme.
  </Step>

  <Step title="Check platform requirements">
    **Android**

    * Set `minSdk` to `24` or newer.
    * No manual callback activity is required.

    **iOS**

    * Set the deployment target to iOS `13.0` or newer.
    * Enable **Keychain Sharing** for the Runner target in Xcode.

    No callback URL type needs to be added manually when using the package's
    default system authentication session.
  </Step>

  <Step title="Initialize the SDK">
    Provide the client key when creating `TheFaithAppAuth`:

    ```dart theme={null}
    import 'package:thefaithapp_auth/thefaithapp_auth.dart';

    const clientKey = String.fromEnvironment('TFA_CLIENT_KEY');

    final auth = TheFaithAppAuth(apiKey: clientKey);
    ```

    Pass the value from your build environment instead of committing it to the
    repository:

    ```bash theme={null}
    flutter run \
      --dart-define=TFA_CLIENT_KEY=replace-with-your-client-key
    ```
  </Step>

  <Step title="Sign in a member">
    Open hosted sign-in from a button or another user action:

    ```dart theme={null}
    Future<TheFaithAuthSession> signInMember() async {
      return auth.signIn();
    }
    ```

    After the member finishes signing in, the package returns to the app and
    saves the session securely.
  </Step>

  <Step title="Call a v1 endpoint">
    Use the authorized client for protected API requests:

    ```dart theme={null}
    import 'dart:convert';

    Future<Map<String, dynamic>> loadCurrentMember() async {
      final client = auth.authorizedClient();

      try {
        final response = await client.get(auth.apiUri('/v1/user'));
        final body = jsonDecode(response.body) as Map<String, dynamic>;

        if (response.statusCode < 200 || response.statusCode >= 300) {
          throw Exception(body['message'] ?? 'The request failed.');
        }

        return Map<String, dynamic>.from(body['data'] as Map);
      } finally {
        client.close();
      }
    }
    ```

    Use `auth.apiUri('/v1/...')` for other endpoints in the API Reference.
  </Step>
</Steps>

## Restore the saved session

Check for a saved session when the app starts:

```dart theme={null}
final session = await auth.currentSession();

if (session != null) {
  print('Welcome back, ${session.member.name}');
}
```

If `currentSession()` returns `null`, show the sign-in action again.

## Sign out

Revoke the member session and remove its saved copy:

```dart theme={null}
await auth.signOut();
```

Release the SDK's resources when the owning service or widget is disposed:

```dart theme={null}
auth.dispose();
```

## Handle SDK errors

Catch `TheFaithAuthException` to show an appropriate message:

```dart theme={null}
try {
  await auth.signIn();
} on TheFaithAuthException catch (error) {
  switch (error.code) {
    case TheFaithAuthErrorCode.cancelled:
      // The member closed the sign-in session.
      break;
    default:
      // Show error.message or your own friendly message.
      break;
  }
}
```

## Troubleshooting

| Problem                                                  | What to check                                                                                               |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| The redirect is rejected                                 | Confirm the value added with **Add Flutter app** matches the application's ID with `.thefaithapp` appended. |
| The app does not reopen after sign-in                    | Stop and rebuild the app, then confirm the installed app uses the expected application ID.                  |
| `MissingPluginException` appears                         | Stop the running app and perform a full rebuild after adding the package.                                   |
| A protected request says the member is not authenticated | Call `signIn()` or restore a saved session before creating the request.                                     |
| The session is not restored on iOS                       | Confirm **Keychain Sharing** is enabled for the Runner target.                                              |

## Next steps

* Browse the endpoint groups in the API Reference navigation.
* Read [Pagination and Errors](/api-reference/pagination-and-errors) before
  loading lists or adding retry behavior.
* Use the public
  [standalone sample](https://github.com/thefaithapp/thefaithapp-auth-flutter/tree/main/example)
  as a compact reference implementation.