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

# Hosted Auth Guide

> Sign members into your app with TheFaithApp-hosted auth, then use member tokens for API calls.

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

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:

```text theme={null}
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.

<Note>
  Hosted auth always runs on the TheFaithApp auth host. Church custom domains do not host the auth page.
</Note>

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

```mermaid theme={null}
sequenceDiagram
    participant App as Your app
    participant API as TheFaithApp API
    participant Auth as Hosted auth page
    participant User as Member

    App->>API: POST /v1/auth/start
    API-->>App: auth_url
    App->>Auth: Open auth_url
    User->>Auth: Sign in or create account
    Auth->>API: Complete hosted auth
    API-->>Auth: redirect_to with code
    Auth-->>App: redirect_uri?code=...&state=...
    App->>API: POST /v1/auth/token
    API-->>App: access_token + member
    App->>API: GET /v1/audios with API key + bearer token
```

## 1. Start Sign-In

```bash theme={null}
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:

```json theme={null}
{
  "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:

```text theme={null}
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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```http theme={null}
X-API-Key: your-client-api-key
Authorization: Bearer member-bearer-token
```

Example:

```bash theme={null}
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:

```dart theme={null}
final auth = TheFaithAppAuth(apiKey: 'your-client-api-key');
```

For the full package setup and API request example, follow the
[Flutter SDK Quickstart](/api-reference/flutter-sdk).

React Native and Expo:

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

Follow the [React Native SDK Quickstart](/api-reference/react-native-sdk) for
the config plugin, native build, and API request example.

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

## Optional PKCE

Public clients can include PKCE values when starting auth:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
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.