authentication

85 notes in this subject, read out of this brain and free to use. This is page 2 of 2.

Enable Native API in Clerk Dashboard

Open the Native applications page in the Clerk Dashboard and ensure Native API is enabled. This is required for any Expo integration that uses @clerk/expo.

useHostedAuth hook for Clerk hosted authentication

Call startHostedAuth() from the useHostedAuth() hook to open Clerk Account Portal in a browser authentication session. startHostedAuth() accepts mode: 'sign-in' | 'sign-up' (defaults to sign-in page). It resolves with null createdSessionId when the user dismisses the browser without finishing and throws when authentication fails. After authentication completes, the SDK closes the browser session, activates the new session, and updates useAuth() with the signed-in state.

Hosted authentication example with useHostedAuth()

Example using useHostedAuth() and useAuth() to handle hosted authentication: import { useAuth } from '@clerk/expo'; import { useHostedAuth } from '@clerk/expo/hosted-auth'; import { ActivityIndicator, Button, Text, View } from 'react-native'; export default function MainScreen() { const { isLoaded, isSignedIn } = useAuth(); const { startHostedAuth } = useHostedAuth(); const handleSignUp = async () => { try { await startHostedAuth({ mode: 'sign-up' }); } catch (error) { } }; if (!isLoaded) { return <ActivityIndicator size="large" />; } return ( <View> {isSignedIn ? ( <Text>You're signed in</Text> ) : ( <Button title="Sign up" onPress={handleSignUp} /> )} </View> ); }

AuthView native UI component usage

<AuthView /> renders a complete native sign-in and sign-up interface that handles email, phone, passkeys, multi-factor authentication, and social connections. It renders inline in your React Native view hierarchy so you can place it in a modal, route, or full-screen view. Accepts mode="signIn" | "signUp" | "signInOrUp" (default), isDismissible boolean for native dismiss button control, and onDismiss callback.

UserButton and UserProfileView components

<UserButton /> takes no props, displays the signed-in user's profile image or initials, and opens the native <UserProfileView /> when tapped. In <UserProfileView /> users can manage personal information, security settings, and sign out.

App Store Guideline 4.8 Sign in with Apple requirement

On iOS, App Store Guideline 4.8 requires that any app offering third-party social sign-in must also offer Sign in with Apple.

AuthView native UI example with modal

Example opening <AuthView /> in a modal with useAuth() state management: import { useAuth } from '@clerk/expo'; import { AuthView, UserButton } from '@clerk/expo/native'; import { useState } from 'react'; import { ActivityIndicator, Button, Modal, View } from 'react-native'; export default function MainScreen() { const { isLoaded, isSignedIn } = useAuth({ treatPendingAsSignedOut: false }); const [isAuthOpen, setIsAuthOpen] = useState(false); if (!isLoaded) { return <ActivityIndicator size="large" />; } return ( <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}> {isSignedIn ? <UserButton /> : <Button title="Sign up" onPress={() => setIsAuthOpen(true)} />} <Modal animationType="slide" visible={isAuthOpen} presentationStyle="pageSheet" onRequestClose={() => setIsAuthOpen(false)}> <AuthView onDismiss={() => setIsAuthOpen(false)} /> </Modal> </View> ); }

AuthView modal mounting requirement

Keep the <Modal> that contains <AuthView /> mounted at the same level as your signed-in and signed-out content. If you render it only inside signed-out content, auth state can change while session tasks are still pending, and your conditional render unmounts the modal too early.

AuthView treatPendingAsSignedOut option

Pass treatPendingAsSignedOut: false to useAuth() when using <AuthView /> so pending session tasks are not treated as signed out.

AuthView social connections and OAuth setup

<AuthView /> automatically shows sign-in buttons for any social connections enabled in Clerk Dashboard and handles flows internally, so you don't need expo-crypto or native sign-in hooks. Native OAuth still requires credential setup in Clerk Dashboard and provider consoles. Without proper setup, buttons appear but fail when tapped.

Custom flow with useSignUp hook example

Example using useSignUp() to build email and password sign-up with email code verification: import { useAuth, useSignUp } from '@clerk/expo'; import { useState } from 'react'; import { Button, Text, TextInput, View } from 'react-native'; export default function MainScreen() { const { isLoaded, isSignedIn } = useAuth(); const { signUp } = useSignUp(); const [emailAddress, setEmailAddress] = useState(''); const [password, setPassword] = useState(''); const [code, setCode] = useState(''); const [isVerifying, setIsVerifying] = useState(false); const handleSignUp = async () => { const { error } = await signUp.password({ emailAddress, password }); if (error) { console.error(JSON.stringify(error, null, 2)); return; } const { error: sendError } = await signUp.verifications.sendEmailCode(); if (sendError) { console.error(JSON.stringify(sendError, null, 2)); return; } setIsVerifying(true); }; const handleVerify = async () => { const { error } = await signUp.verifications.verifyEmailCode({ code }); if (error) { console.error(JSON.stringify(error, null, 2)); return; } await signUp.finalize(); }; if (!isLoaded) { return null; } if (isSignedIn) { return <Text>You're signed in</Text>; } if (isVerifying) { return ( <View> <TextInput value={code} placeholder="Enter your verification code" onChangeText={setCode} keyboardType="numeric" /> <Button title="Verify" onPress={handleVerify} /> </View> ); } return ( <View> <TextInput autoCapitalize="none" value={emailAddress} placeholder="Enter email" onChangeText={setEmailAddress} keyboardType="email-address" /> <TextInput value={password} placeholder="Enter password" secureTextEntry onChangeText={setPassword} /> <Button title="Sign up" onPress={handleSignUp} /> <View nativeID="clerk-captcha" /> </View> ); }

Clerk Core 3 method return behavior

In Core 3, methods such as signUp.password() and signUp.verifications.verifyEmailCode() return { error } instead of throwing for validation errors. When verification completes the sign-up, signUp.finalize() converts it into an active session and updates useAuth() with the signed-in state.

useSignIn hook with finalize navigate callback

The useSignIn() sign-in flow uses finalize() which accepts a navigate callback for handling session tasks before redirecting. Example: await signIn.finalize({ navigate: ({ session, decorateUrl }) => { if (session?.currentTask) return; router.replace(decorateUrl('/') as Href); } });

useSignInWithGoogle hook from @clerk/expo/google

Use useSignInWithGoogle() hook from @clerk/expo/google to add native Sign in with Google buttons to custom screens. Returns startGoogleAuthenticationFlow() that resolves with { createdSessionId, setActive }. Requires development build and @clerk/expo-google-signin config plugin.

useSignInWithApple hook from @clerk/expo/apple

Use useSignInWithApple() hook from @clerk/expo/apple to add native Sign in with Apple buttons to custom screens. Returns startAppleAuthenticationFlow() that resolves with { createdSessionId, setActive }. Requires development build, expo-apple-authentication, and expo-crypto packages.

useUser hook and Show component

Use useUser() to read user data. Use useClerk() to access signOut(). Use <Show> component to protect content conditionally. <Show when="signed-in"> renders when user is signed in, <Show when="signed-out"> renders when signed out. <Show> replaces legacy <SignedIn>, <SignedOut>, and <Protect> components.

Reading signed-in user data example

Example using useUser(), useClerk(), and <Show> to read user data and protect content: import { Show, useClerk, useUser } from '@clerk/expo'; import { Link } from 'expo-router'; import { Pressable, Text, View } from 'react-native'; export default function HomeScreen() { const { user } = useUser(); const { signOut } = useClerk(); return ( <View> <Show when="signed-in"> <Text>Hello, {user?.firstName ?? 'friend'}</Text> <Pressable onPress={() => signOut()}> <Text>Sign out</Text> </Pressable> </Show> <Show when="signed-out"> <Link href="/(auth)/sign-in"> <Text>Sign in</Text> </Link> </Show> </View> ); }

Show component authorization predicates

<Show> component accepts authorization predicates like when={{ role: '...' }} and when={{ permission: '...' }} in addition to when="signed-in" and when="signed-out".

@clerk/expo installation with npx expo install

Install @clerk/expo and expo-secure-store using npx expo install to ensure version compatibility with your Expo SDK. Command: npx expo install @clerk/expo expo-secure-store. expo-secure-store is a peer dependency that Clerk uses through @clerk/expo/token-cache to encrypt session tokens with iOS Keychain and Android Keystore.

Clerk hosted authentication packages

For hosted authentication, also install expo-auth-session, expo-crypto, and expo-web-browser. These packages are required for Clerk to open the browser authentication session.

Expo CLI authentication commands

Expo CLI authentication: `npx expo register` (register account), `npx expo login` (login), `npx expo whoami` (check authenticated account), `npx expo logout` (logout). Credentials are shared with EAS CLI. Authentication code-signs manifests for secure OTA usage (like HTTPS).

OAuth/PKCE changes must not shorten verifier entropy, skip state comparison, or widen redirect URI

OAuth/PKCE changes in packages/expo-auth-session/src/ or the CLI login flow must not shorten verifier entropy, skip the state comparison, widen the accepted redirect URI, or leave a session valid after logout (issues #45802, #44938).

expo-auth-session dependency on expo-application

expo-auth-session added a dependency on expo-application as it is no longer a dependency of the expo package.

expo-auth-session prompt parameter accepts array

The prompt parameter of AuthRequest in expo-auth-session now accepts multiple values as an array.

expo-auth-session: useProxy option deprecated

The `useProxy` option in expo-auth-session has been deprecated. The `makeRedirectUriAsync` method was replaced with `makeRedirectUri`. A deprecation warning is shown when `promptAsync` uses the `useProxy` option. All auth proxy APIs have been removed.

Give your agent this brain