Authentication

Add a URL scheme to your app

The OAuth redirect comes back to your app via a deep link. Register a custom URL scheme in app.json — this becomes the prefix for your redirect URI (e.g. scheme com.example.myapp → redirect com.example.myapp://callback).

Pick a unique value, typically a reverse-DNS identifier for your app. It must contain only lowercase letters, numbers, dots, and hyphens. Custom URL schemes have no ownership registry on either platform: on Android, if two installed apps claim the same scheme the OS shows a disambiguation dialog asking the user which app to open, and on iOS there is no defined process for which app wins a duplicated scheme — so choose a scheme unique to your app:

app.json
{
  "expo": {
    "scheme": "com.example.myapp"
  }
}

Register your redirect URI

Your redirect URI is the value from step 1 — your scheme plus ://callback (e.g. com.example.myapp://callback). Add it as a Callback URI in your app's settings in the YouVersion Platform console.

In code, expo-linking builds the same URI for you — install it with npx expo install expo-linking:

Code
import * as Linking from "expo-linking";

const redirectUri = Linking.createURL("callback"); // e.g. com.example.myapp://callback

Enable auth on the provider

Pass the auth config to YouVersionProvider:

app/_layout.tsx
import { YouVersionProvider } from "@youversion/platform-react-native-expo-ui";
import * as Linking from "expo-linking";
import { Stack } from "expo-router";
import { GestureHandlerRootView } from "react-native-gesture-handler";

export default function RootLayout() {
  const appKey = process.env.EXPO_PUBLIC_YOUVERSION_APP_KEY;
  const redirectUri = Linking.createURL("callback");

  if (!appKey) return null;

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <YouVersionProvider
        appKey={appKey}
        auth={{ redirectUri, scopes: ["profile", "email"] }}
      >
        <Stack screenOptions={{ headerShown: false }} />
      </YouVersionProvider>
    </GestureHandlerRootView>
  );
}

Add the callback route

Create a route that matches the path in your redirectUri (here, callback). The SDK completes the token exchange inside the in-app browser session, so the route only needs to return the user to your app:

app/callback.tsx
import { useRouter } from "expo-router";
import { useEffect } from "react";

export default function AuthCallback() {
  const router = useRouter();
  useEffect(() => {
    if (router.canGoBack()) {
      router.back();
    } else {
      router.replace("/");
    }
  }, [router]);
  return null;
}

Add Sign in with YouVersion (Optional)

Drop in the pre-styled button anywhere under the provider. It handles sign-in and sign-out for you:

app/(tabs)/profile.tsx
import { YouVersionAuthButton } from "@youversion/platform-react-native-expo-ui";
import { useColorScheme, View } from "react-native";

export default function ProfileScreen() {
  const isDark = useColorScheme() === "dark";

  return (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <YouVersionAuthButton
        mode="auto"
        background={isDark ? "dark" : "light"}
        outline
      />
    </View>
  );
}

See YouVersionAuthButton for styling props.

Use our Authentication hook (Optional)

When you need a custom sign-in UI, call signIn() and signOut() from useYVAuth directly:

SignInButton.tsx
import { useYVAuth } from "@youversion/platform-react-native-expo-core";
import { Button, Text } from "react-native";

export function SignInButton() {
  const { isAuthenticated, isLoading, userInfo, signIn, signOut } = useYVAuth();

  if (isLoading) return null;

  if (isAuthenticated) {
    return (
      <>
        <Text>Welcome, {userInfo?.name}!</Text>
        <Button title="Sign out" onPress={() => signOut()} />
      </>
    );
  }

  return <Button title="Sign in with YouVersion" onPress={() => signIn()} />;
}