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

Add the package

Add the package to your pubspec.yaml:

dependencies:
  thefaithapp_auth: ^0.1.0

Install it:

flutter pub get

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

In the TheFaithApp dashboard:

Open Settings > Developer Access.
Click Add Flutter app.
Append .thefaithapp to your application ID.
Add the app and copy your client API key.

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

com.example.app.thefaithapp

The dashboard creates the callback expected by the package:

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.

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.

Initialize the SDK

Provide the client key when creating TheFaithAppAuth:

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:

flutter run \
  --dart-define=TFA_CLIENT_KEY=replace-with-your-client-key

Open hosted sign-in from a button or another user action:

Future<TheFaithAuthSession> signInMember() async {
  return auth.signIn();
}

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

Call a v1 endpoint

Use the authorized client for protected API requests:

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.

Restore the saved session

Check for a saved session when the app starts:

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:

await auth.signOut();

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

auth.dispose();

Handle SDK errors

Catch TheFaithAuthException to show an appropriate message:

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 before loading lists or adding retry behavior.
Use the public standalone sample as a compact reference implementation.

Get Started

Endpoints

Flutter SDK Quickstart

Use the API from Flutter

Before you begin

Restore the saved session

Sign out

Handle SDK errors

Troubleshooting

Next steps

​Use the API from Flutter

​Before you begin

​Restore the saved session

​Sign out

​Handle SDK errors

​Troubleshooting

​Next steps

Use the API from Flutter

Before you begin

Restore the saved session

Sign out

Handle SDK errors

Troubleshooting

Next steps