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

# React Native SDK Quickstart

> Add hosted member sign-in and authenticated v1 API requests to an iOS or Android React Native app.

# Use the API from React Native

The `@thefaithapp/auth-react-native` package signs a member in through
TheFaithApp and sends authenticated `v1` API requests from React Native and
Expo apps. Your app does not need to host a callback website.

## Before you begin

You need:

* an Expo SDK 57 app targeting iOS or Android
* its Android application ID and iOS bundle ID
* a client API key from `Settings > Developer Access`

<Steps>
  <Step title="Add the package">
    Install the SDK and its Expo modules:

    ```bash theme={null}
    npm install @thefaithapp/auth-react-native
    npx expo install expo-application expo-crypto expo-secure-store expo-web-browser
    ```
  </Step>

  <Step title="Add the config plugin">
    Add the SDK plugin and your application identifiers to `app.json`:

    ```json theme={null}
    {
      "expo": {
        "plugins": ["@thefaithapp/auth-react-native"],
        "ios": {
          "bundleIdentifier": "com.example.app"
        },
        "android": {
          "package": "com.example.app"
        }
      }
    }
    ```

    The plugin adds the mobile callback to both native projects when you build
    the app.
  </Step>

  <Step title="Register your React Native app">
    In the TheFaithApp dashboard:

    1. Open `Settings > Developer Access`.
    2. Click **Add React Native app**.
    3. Append `.thefaithapp` to your application ID.
    4. Add the app and copy your client API key.

    For an application ID of `com.example.app`, enter:

    ```text theme={null}
    com.example.app.thefaithapp
    ```

    The dashboard creates the callback expected by the package:

    ```text theme={null}
    com.example.app.thefaithapp://auth/callback
    ```

    If iOS and Android use different identifiers, register both callbacks.
    Avoid underscores because they cannot be used in a callback URI scheme.
  </Step>

  <Step title="Create a native build">
    Rebuild the app so the native callback configuration is included:

    ```bash theme={null}
    npx expo run:ios
    # or
    npx expo run:android
    ```

    Use a development build or standalone app for this flow. Expo Go cannot be
    rebuilt with your application's callback scheme.
  </Step>

  <Step title="Initialize the SDK">
    Provide the client key when creating `TheFaithAppAuth`:

    ```tsx theme={null}
    import { TheFaithAppAuth } from '@thefaithapp/auth-react-native'

    const auth = new TheFaithAppAuth({
      apiKey: process.env.EXPO_PUBLIC_THEFAITHAPP_API_KEY!,
    })
    ```

    Supply the value from your development or build environment instead of
    committing it to source control.
  </Step>

  <Step title="Sign in a member">
    Start sign-in from a button or another user action:

    ```tsx theme={null}
    const session = await auth.signIn()
    console.log(session.member.name)
    ```

    The package returns to the app after hosted sign-in and stores the member
    session securely.
  </Step>

  <Step title="Call a v1 endpoint">
    Use `authorizedFetch` for protected API requests:

    ```tsx theme={null}
    const response = await auth.authorizedFetch('/v1/user')
    const body = await response.json()

    if (!response.ok) {
      throw new Error(body.message ?? 'The request failed.')
    }
    ```

    Pass another relative `/v1/...` path to call endpoints from the API
    Reference.
  </Step>
</Steps>

## Restore the saved session

Check for a saved session when the app starts:

```tsx theme={null}
const session = await auth.currentSession()

if (session) {
  console.log(`Welcome back, ${session.member.name}`)
}
```

## Access the bearer token

When an integration needs the token directly:

```tsx theme={null}
const token = await auth.accessToken()
```

Do not log the token or include it in analytics and crash reports.

## Sign out

Revoke the member session and remove its saved copy:

```tsx theme={null}
await auth.signOut()
```

## Handle SDK errors

```tsx theme={null}
import { TheFaithAuthError } from '@thefaithapp/auth-react-native'

try {
  await auth.signIn()
} catch (error) {
  if (error instanceof TheFaithAuthError && error.code === 'cancelled') {
    // The member closed the sign-in session.
  }
}
```

## Troubleshooting

| Problem                                                  | What to check                                                                                                  |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| The redirect is rejected                                 | Confirm the value added with **Add React Native app** matches the application ID with `.thefaithapp` appended. |
| The app does not reopen after sign-in                    | Rebuild the native app after adding the config plugin and confirm the installed application ID.                |
| Sign-in does not return while using Expo Go              | Create an Expo development build or standalone app.                                                            |
| A protected request says the member is not authenticated | Call `signIn()` or restore a saved session before sending the request.                                         |

## Next steps

* Browse the endpoint groups in the API Reference navigation.
* Read [Pagination and Errors](/api-reference/pagination-and-errors) before
  loading lists or adding retry behavior.
* Use the public
  [standalone sample](https://github.com/thefaithapp/thefaithapp-auth-react-native/tree/main/example)
  as a compact reference implementation.