Make your first request

This quickstart uses hosted auth to obtain a member token, then calls GET /v1/user with both required credentials.

Before you begin

In Settings > Developer Access in the TheFaithApp dashboard:

Copy your public client key.
Add the exact callback URL that will receive the member after sign-in.

For local development, save a dedicated callback such as http://localhost:3000/auth/callback. Production and local callback URLs must each be added explicitly.

Create a hosted sign-in URL

Generate a cryptographically random state and a 43–128 character PKCE verifier. Send the verifier’s base64url-encoded SHA-256 challenge with your callback URL.

curl -X POST https://api.thefaithapp.com/v1/auth/start \
  -H "Content-Type: application/json" \
  -d '{
    "client_key": "your-public-client-key",
    "redirect_uri": "https://example.com/auth/callback",
    "state": "replace-with-at-least-16-random-characters",
    "code_challenge": "base64url-sha256-of-your-code-verifier",
    "code_challenge_method": "S256"
  }'

The response includes auth_url. Open it in the system browser or a browser-based mobile auth session.

Validate the callback

After sign-in, the member returns to your callback URL:

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

Reject the callback if state does not exactly match the value stored when sign-in began. Exchange code immediately; it is short-lived and single-use.

Exchange the code

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

Store the returned access_token in secure server-side storage, an HTTP-only secure session cookie, Keychain, or Keystore.

Load the member

curl https://api.thefaithapp.com/v1/user \
  -H "X-API-Key: your-public-client-key" \
  -H "Authorization: Bearer your-member-access-token" \
  -H "Accept: application/json"

A successful response contains status: "Success" and the member record in data.

JavaScript example

const response = await fetch('https://api.thefaithapp.com/v1/user', {
  headers: {
    Accept: 'application/json',
    'X-API-Key': process.env.THEFAITHAPP_CLIENT_KEY,
    Authorization: `Bearer ${memberAccessToken}`,
  },
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.message ?? error.error_message ?? 'TheFaithApp request failed');
}

const { data: member } = await response.json();

The client key is a public church-app identifier, not an authentication secret. Keep member access tokens out of source code and store them in a secure server-side session, Keychain, or Keystore.

Next steps

Building with Flutter? Follow the Flutter SDK Quickstart.
Building with React Native or Expo? Follow the React Native SDK Quickstart.
Adding in-app giving to Flutter? Follow the Flutter Giving SDK.
Adding in-app giving to React Native or Expo? Follow the React Native Giving SDK.
Read the Hosted Auth Guide before implementing production sign-in.
Review Pagination and Errors for resilient response handling.
Open an endpoint in the reference to see generated cURL, JavaScript, and Python examples.

Get Started

Endpoints

Quickstart

Make your first request

Before you begin

JavaScript example

Next steps

​Make your first request

​Before you begin

​JavaScript example

​Next steps

Make your first request

Before you begin

JavaScript example

Next steps