Authentication

Use this guide to add authentication screens to a React Native app. The SDK provides composable forms and calls the active native Ovok client; 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/next/react and the SDK ThemeProvider from @ovok/native.

1. Add patient email sign-inCopy Anchor Link

Create a sign-in route and compose the screen from its exported children. Patient sign-in requires the tenant code configured on your native client. Pass the same code to the form's existing tenantCode prop.

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. Network error keys are used for recognized transport failures and timeouts only when no HTTP response is present. Other TypeErrors remain generic errors, so a programming bug is not presented as a connectivity problem.

2. Add registration and password recoveryCopy Anchor Link

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 itCopy Anchor Link

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. On the web the same buttons work without those packages; follow Sign in on the web.

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 limitsCopy Anchor Link

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 use the server's Retry-After wait for rate-limit cooldowns, falling back to 60 seconds when there is no hint. 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 controlsCopy Anchor Link

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.

6. Sign in carersCopy Anchor Link

A carer (FHIR RelatedPerson) signs in to the patient app with loginType="RelatedPerson" and the tenant code, and resets a password with the reset form's RelatedPerson type. Carer accounts come from accepting a patient's record-share invite; see Invites and carers.

Integration checklistCopy Anchor Link

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

API referenceCopy Anchor Link

Every export of @ovok/native/auth, with signatures, props and types, is in the auth API reference.