Skip to main content

​
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

​
Supported Sign-In Methods

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. 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

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

​
1. Start Sign-In

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.

​
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

StatusWhen it happensHow to fix it
403The redirect_uri is not saved for this client key.Add the exact redirect URL in Developer Access.
404The client_key is unknown.Confirm you copied the client key from the correct church.
422A required request field is missing or invalid.Check client_key, redirect_uri, code, and PKCE fields.
400The 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.
401A protected API request has a missing or invalid bearer token.Exchange the hosted auth code and use the returned member token.

​
Endpoint Reference