​

Welcome to the TheFaithApp API

The TheFaithApp API allows third-party apps and services to interact with our platform, enabling features such as subscribing users to churches, sending notifications, and more. This API is designed for partners and developers who want to integrate with our ecosystem securely and efficiently.

​

Authentication

All requests to the TheFaithApp API require two forms of authentication:

1. API Key

   • Each client (partner app) is issued a unique API key.
   • This key must be included in the X-API-Key header of every request.

2. Firebase ID Token

   • Each user must authenticate with Firebase to obtain an ID token.
   • This token must be included as a Bearer token in the Authorization header.
   • If using email-password authentication, ensure you collect the user’s name during registration as this is required for our platform to properly identify users.
   • Important: Firebase ID tokens expire after 1 hour (as set by Google). You must implement token refresh logic in your application:
     • On the client side (mobile/web), use the refresh token to obtain new ID tokens when the current one expires.
     • Firebase SDKs handle this automatically if you’re using their client libraries.
     • If you’re implementing your own solution, ensure you refresh tokens before they expire to maintain continuous authentication.

Example headers:

X-API-Key: your-client-api-key
Authorization: Bearer your-firebase-id-token

⚠️ Both headers are required for all endpoints under /v1/open.

​

Getting Started

​

1. Upload Your Firebase Service Account

Before you can access your API key, you must upload your Firebase service account file for the Firebase project you want to use.

• Go to the Dashboard.
• Navigate to the Settings page.
• Upload your Firebase service account JSON file.
• Once uploaded, your API key will be generated and displayed.

​

2. Obtain Your API Key

• After uploading your Firebase service account, your unique API key will be available on the Settings page of the dashboard.
• Keep this key secure. It is required for all API requests.

​

3. Integrate Firebase Authentication

• Set up Firebase Authentication in your app (using the same Firebase project as your service account).
• When a user logs in, retrieve their Firebase ID token using the Firebase SDK.
• If implementing email-password authentication, be sure to collect and store the user’s name during the registration process. This information is essential for our platform to properly identify and manage user accounts.

​

4. Set Up Push Notifications

To receive push notifications in your app, you need to:

1. Get Your Notification Channel Name

   • Go to the Dashboard
   • Navigate to Settings > Developer Tools
   • Under Firebase Configuration, you’ll find your unique notification channel name
   • This channel name is required for configuring push notifications in your app

2. Configure Push Notifications in Your App

   • Use your app’s native Firebase implementation to subscribe to the notification channel
   • The channel name from your dashboard must match the one configured in your app

Platform-specific implementation examples:

Flutter:

// Subscribe to the notification channel
await FirebaseMessaging.instance.subscribeToTopic('your-notification-channel-name');

React Native:

import messaging from '@react-native-firebase/messaging';

// Subscribe to the notification channel
await messaging().subscribeToTopic('your-notification-channel-name');

Android (Java):

FirebaseMessaging.getInstance().subscribeToTopic("your-notification-channel-name")
    .addOnCompleteListener(task -> {
        String msg = task.isSuccessful() ? "Subscribed to channel" : "Subscribe failed";
        Log.d("Firebase", msg);
    });

iOS (Swift):

Messaging.messaging().subscribe(toTopic: "your-notification-channel-name") { error in
    if let error = error {
        print("Failed to subscribe to channel: \(error)")
    } else {
        print("Successfully subscribed to channel")
    }
}

⚠️ Important: Push notifications will not be delivered to your app if:

• The notification channel is not properly configured in your app
• The channel name in your dashboard doesn’t match your app’s configuration
• Firebase Messaging is not properly initialized in your app

Always verify your channel name and ensure proper Firebase configuration before expecting to receive notifications.

​

5. Make Authenticated Requests

• Include both the X-API-Key and Authorization headers in your API requests.

Example using curl:

curl -X POST https://your-api-domain.com/api/v1/open/subscribe \
  -H "X-API-Key: your-client-api-key" \
  -H "Authorization: Bearer your-firebase-id-token" \
  -H "Content-Type: application/json" \
  -d '{"fcm_token": "user-fcm-token"}'

​

Example Workflow

1. Upload your Firebase service account file in the dashboard.
2. Retrieve your API key from the Settings page.
3. User logs in via Firebase in your app.
4. Your app retrieves the Firebase ID token.
5. Your backend (or frontend) sends requests to the TheFaithApp API, including:
   • The API key (as X-API-Key)
   • The Firebase ID token (as Bearer token in Authorization)
6. The API validates both credentials and processes the request.

​

Error Handling

• If either the API key or Firebase token is missing or invalid, the API will return a 401 Unauthorized error.
• If the client is not found or Firebase credentials are missing, a 404 or 401 error will be returned.
• Always check the response for error messages and handle them appropriately in your app.

If you have any questions or need support, please contact our developer support team.