# Authentication

Canonical page: https://docs.ovok.com/native-sdk/guide/modules/auth

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](/native-sdk/guide/how-to/app-shell). The forms need `OvokProvider` from
`@ovok/core/next/react` and the SDK `ThemeProvider` from `@ovok/native`.

## 1. Add patient email sign-in [#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 configured on your native client. Pass the same
code to the form's existing `tenantCode` prop.

```tsx
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](/native-sdk/guide/components/auth/sign-in/) 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](/native-sdk/guide/components/auth/sign-in/form/inputs).
Network error keys are used for recognized transport failures and timeouts only
when no HTTP response is present. Other `TypeError`s remain generic errors, so a
programming bug is not presented as a connectivity problem.

## 2. Add registration and password recovery [#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](/native-sdk/guide/components/auth/register/) and
[password-reset reference](/native-sdk/guide/components/auth/reset-password/) for their compound
components and required props. Add [profile editing](/native-sdk/guide/components/auth/profile/),
[logout](/native-sdk/guide/components/auth/logout-button/), or [account deletion](/native-sdk/guide/components/auth/delete-account-button/)
only where those actions belong in your account UX.

## 3. Add social sign-in when your app needs it [#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](/native-sdk/guide/how-to/installation) 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](/native-sdk/guide/components/auth/sign-in/social-logins/#sign-in-on-the-web).

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

```tsx
<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 [#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 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](/native-sdk/guide/components/auth/).

## 5. Add session and account controls [#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](/native-sdk/guide/components/auth/session/) and the
[public API map](/native-sdk/guide/public-api) for supported imports.

## 6. Sign in carers [#6-sign-in-carers]

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](/native-sdk/guide/how-to/invites-and-carers).

## Integration checklist [#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.

## API reference [#api-reference]

Every export of `@ovok/native/auth`, with signatures, props and types, is in the [`auth` API reference](/native-sdk/reference/auth).