Hosted Auth Guide

Hosted auth lets your app sign members in without managing auth provider credentials or building your own member login screen. Your app sends the member to a TheFaithApp-hosted page, receives a one-time code on your callback URL, exchanges that code for a member token, and then uses that token for normal API calls.

When To Use It

Use hosted auth for external web or mobile apps that need to read or update church-scoped member data through the v1 API. The member signs in once. After that, store the returned TheFaithApp member token securely and use it for future API calls.

What You Need

A client key from Settings > Developer Access
One or more saved Redirect URLs
A backend or mobile client that can exchange the returned code for a token
A place to store the returned member token securely

The hosted sign-in page supports:

Google
Apple
Email/password sign in
Email/password account creation with display name

New members are created automatically under the church identified by the client key. Existing members are updated from the verified sign-in profile when they sign in.

Redirect URLs

Add every callback that can receive auth codes in Settings > Developer Access. For Flutter, select Add Flutter app and enter your app’s application ID with .thefaithapp appended. For example, enter com.example.app.thefaithapp for an app whose application ID is com.example.app. TheFaithApp registers com.example.app.thefaithapp://auth/callback automatically. For React Native and Expo, select Add React Native app. Enter the same application ID with .thefaithapp appended; the React Native SDK config plugin registers the resulting callback in the native iOS and Android projects. Examples:

https://example.com/auth/callback
https://staging.example.com/auth/callback
mychurch://auth/callback
com.example.mychurch://auth/callback

The redirect_uri you send to the API must exactly match one saved Redirect URL. If you use a mobile app, register the same deep link or app link scheme in your mobile project.

Hosted auth always runs on the TheFaithApp auth host. Church custom domains do not host the auth page.

Full Flow

Generate a random state value in your app.
Call POST /v1/auth/start with your client_key, redirect_uri, and state.
Open the returned auth_url in a browser tab, mobile browser, or mobile auth session.
The member signs in or creates an account.
TheFaithApp redirects to your redirect_uri with code and state.
Confirm the returned state matches the one you generated.
Call POST /v1/auth/token with the one-time code.
Store the returned access_token.
Call protected v1 endpoints with both X-API-Key and Authorization.

curl -X POST https://api.thefaithapp.com/v1/auth/start \
  -H "Content-Type: application/json" \
  -d '{
    "client_key": "your-client-api-key",
    "redirect_uri": "https://example.com/auth/callback",
    "state": "replace-with-random-state"
  }'

Example response:

{
  "auth_url": "https://auth.thefaithapp.com/member/sign-in?client_key=your-client-api-key&redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fcallback&state=replace-with-random-state",
  "client": {
    "id": 45,
    "name": "Example Church",
    "image": "clients/example-logo.png",
    "image_url": "https://cdn.example.com/clients/example-logo.png",
    "about": null,
    "public_uuid": "11111111-2222-3333-4444-555555555555"
  },
  "redirect_uri": "https://example.com/auth/callback",
  "providers": ["google", "apple", "email"]
}

Open auth_url for the member. Do not iframe the hosted auth page.

2. Receive The Code

After sign-in, TheFaithApp redirects back to your callback:

https://example.com/auth/callback?code=one-time-code&state=replace-with-random-state

Your app should:

read code
read state
reject the callback if state does not match the value you generated
exchange code immediately

Authorization codes are short-lived and can only be used once.

3. Exchange The Code

curl -X POST https://api.thefaithapp.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_key": "your-client-api-key",
    "code": "one-time-code",
    "redirect_uri": "https://example.com/auth/callback"
  }'

Example response:

{
  "access_token": "member-bearer-token",
  "token_type": "Bearer",
  "member": {
    "id": 123,
    "name": "Jane Member",
    "email": "jane@example.com",
    "client_id": 45,
    "uuid": "member-user-id"
  }
}

Store access_token securely. For mobile apps, use secure device storage such as Keychain or Keystore. For server-rendered web apps, keep the token server-side or in an HTTP-only secure session cookie.

4. Call The API

Every protected v1 request needs both headers:

X-API-Key: your-client-api-key
Authorization: Bearer member-bearer-token

Example:

curl https://api.thefaithapp.com/v1/audios?per_page=3 \
  -H "X-API-Key: your-client-api-key" \
  -H "Authorization: Bearer member-bearer-token" \
  -H "Accept: application/json"

Mobile Apps

For mobile apps, use the platform’s browser-based auth session:

iOS: ASWebAuthenticationSession
Android: Chrome Custom Tabs or the AppAuth browser flow
React Native or Flutter: use a browser auth/session package that supports callback URLs

Use a redirect URL your app can receive, such as an app link, universal link, or custom scheme. The exact value must be saved in Developer Access before it can be used. For the TheFaithApp mobile SDKs, use Add Flutter app or Add React Native app in Developer Access so you only enter the package name. The dashboard creates the exact callback URL expected by the SDK. Flutter:

final auth = TheFaithAppAuth(apiKey: 'your-client-api-key');

For the full package setup and API request example, follow the Flutter SDK Quickstart. React Native and Expo:

const auth = new TheFaithAppAuth({ apiKey: 'your-client-api-key' })

Follow the React Native SDK Quickstart for the config plugin, native build, and API request example.

A mobile callback is handled by the installed app. Mobile developers do not need to host a separate website just to receive the authorization code.

Optional PKCE

Public clients can include PKCE values when starting auth:

{
  "client_key": "your-client-api-key",
  "redirect_uri": "mychurch://auth/callback",
  "state": "replace-with-random-state",
  "code_challenge": "base64url-sha256-code-verifier",
  "code_challenge_method": "S256"
}

Then include the matching code_verifier during token exchange:

{
  "client_key": "your-client-api-key",
  "code": "one-time-code",
  "redirect_uri": "mychurch://auth/callback",
  "code_verifier": "original-random-code-verifier"
}

PKCE is recommended for mobile and other public clients.

Logout

To invalidate a member token, call POST /v1/auth/logout with the same API key and bearer token:

curl -X POST https://api.thefaithapp.com/v1/auth/logout \
  -H "X-API-Key: your-client-api-key" \
  -H "Authorization: Bearer member-bearer-token" \
  -H "Accept: application/json"

Common Errors

Status	When it happens	How to fix it
`403`	The `redirect_uri` is not saved for this client key.	Add the exact redirect URL in Developer Access.
`404`	The `client_key` is unknown.	Confirm you copied the client key from the correct church.
`422`	A required request field is missing or invalid.	Check `client_key`, `redirect_uri`, `code`, and PKCE fields.
`400`	The code is invalid, expired, already used, or the redirect URL does not match.	Start a fresh hosted auth flow and exchange the new code quickly.
`401`	A protected API request has a missing or invalid bearer token.	Exchange the hosted auth code and use the returned member token.

Endpoint Reference

Open the Hosted Auth section in the API Reference navigation for the live request builder, complete schemas, and generated examples for each auth route.

Get Started

Endpoints

Hosted Auth Guide

Hosted Auth Guide

When To Use It

What You Need

Redirect URLs

Full Flow

2. Receive The Code

3. Exchange The Code

4. Call The API

Mobile Apps

Optional PKCE

Logout

Common Errors

Endpoint Reference

​Hosted Auth Guide

​When To Use It

​What You Need

​Supported Sign-In Methods

​Redirect URLs

​Full Flow

​1. Start Sign-In

​2. Receive The Code

​3. Exchange The Code

​4. Call The API

​Mobile Apps

​Optional PKCE

​Logout

​Common Errors

​Endpoint Reference

Hosted Auth Guide

When To Use It

What You Need

Supported Sign-In Methods

Redirect URLs

Full Flow

1. Start Sign-In

2. Receive The Code

3. Exchange The Code

4. Call The API

Mobile Apps

Optional PKCE

Logout

Common Errors

Endpoint Reference