Skip to main content

Authentication

Use this guide to add authentication screens to a React Native app. The SDK provides composable forms and calls the active OvokClient; your app owns routes, session UX, error messages, and account-specific policy.

Before you start, install the native dependencies for the auth features you use and mount the app shell and providers. The forms need OvokProvider from @ovok/core and the SDK ThemeProvider from @ovok/native.

1. Add patient email sign-in​

Create a sign-in route and compose the screen from its exported children. Patient sign-in requires the tenant code for your OVOK environment.

import { SignIn } from "@ovok/native";
import { useRouter } from "expo-router";
import { Alert } from "react-native";

const tenantCode = process.env.EXPO_PUBLIC_TENANT_CODE;

if (!tenantCode) {
  throw new Error("Set EXPO_PUBLIC_TENANT_CODE in your app environment");
}

export default function SignInScreen() {
  const router = useRouter();

  return (
    <SignIn>
      <SignIn.Header>
        <SignIn.Header.Title />
      </SignIn.Header>
      <SignIn.EmailForm
        loginType="Patient"
        tenantCode={tenantCode}
        onSuccess={() => router.replace("/home")}
        onError={(error) => Alert.alert("Sign-in failed", error.message)}
      >
        <SignIn.EmailForm.Inputs />
        <SignIn.EmailForm.SigninButton />
      </SignIn.EmailForm>
    </SignIn>
  );
}

Replace /home with an authenticated route in your app. The callback runs after the client accepts the login; use it to update app navigation or refresh patient-specific state. Keep EXPO_PUBLIC_ values limited to public configuration, not credentials.

For practitioner sign-in, set loginType="Practitioner"; tenantCode is optional for that variant. See Sign-in components for form children, validation, and callback types.

The built-in auth fields show validation errors after the person changes a field or submits the form. Focusing and leaving an untouched required field does not show an error; see the sign-in input reference.

2. Add registration and password recovery​

Give registration and password recovery their own routes so users can reach them from sign-in and return to the correct point in your app. Compose the exported Register and ResetPassword children for the fields and actions you want to show. The app decides where successful registration or a reset request leads next.

Use the detailed registration reference and password-reset reference for their compound components and required props. Add profile editing, logout, or account deletion only where those actions belong in your account UX.

3. Add social sign-in when your app needs it​

Social buttons require their native packages and platform configuration before the screen can render them. Follow the installation guide to configure Google Sign-In and Apple Sign-In in the native build. Apple Sign-In is available on iOS.

Compose the buttons inside SignIn.SocialLogins and provide the OVOK integration ID and provider client IDs:

<SignIn.SocialLogins>
  <SignIn.SocialLogins.GoogleLogin
    googleIosClientId={googleIosClientId}
    googleWebClientId={googleWebClientId}
    internalId={googleInternalId}
    onSuccess={handleSignIn}
    onError={handleSignInError}
  >
    <SignIn.SocialLogins.GoogleLogin.Icon />
    <SignIn.SocialLogins.GoogleLogin.Text />
  </SignIn.SocialLogins.GoogleLogin>
  <SignIn.SocialLogins.AppleLogin
    internalId={appleInternalId}
    onSuccess={handleSignIn}
    onError={handleSignInError}
  >
    <SignIn.SocialLogins.AppleLogin.Icon />
    <SignIn.SocialLogins.AppleLogin.Text />
  </SignIn.SocialLogins.AppleLogin>
</SignIn.SocialLogins>

Treat user cancellation as a normal outcome. Keep provider errors visible during development and show app-owned recovery messaging when a login fails.

4. Handle MFA and rate limits​

When the backend requires MFA, the email form switches to its verification step and renders the code field. The SDK manages the field and submit state; your app still handles success and error callbacks. The keyboard flow moves from email to password to submit, then focuses the MFA field when verification is needed.

The sign-in, registration, and reset-password forms recognize supported rate-limit responses and apply a cooldown. For a custom form, use getRateLimitDetails, setRateLimitFormError, and useRateLimitCooldown from the public auth exports. A backend response outside the supported shape still needs your app's normal error handling. See Authentication API details.

5. Add session and account controls​

Use SessionList when users need to inspect or revoke sessions on other devices. useSession exposes session operations for a custom account screen. Logout and account-deletion controls call the active client; provide their success and error callbacks to keep navigation and messaging in the app's control.

See the session reference and the public API map for supported imports.

Integration checklist​

  • The auth routes render below OvokProvider and the SDK theme provider.
  • Patient sign-in receives a tenant code from public app configuration.
  • Native social sign-in packages and config plugins are included only when used.
  • The app handles success, failure, cancellation, and post-login navigation.
  • The native app is rebuilt after adding or changing a native auth dependency.