Skip to main content

Authentication

The SDK provides typed methods for password login, registration, password recovery, social login, multi-factor verification, and session management. The backend remains authoritative for identity, authentication policy, project membership, and access.

For required project setup and end-user flows, follow Ovok Authentication. For what an authenticated user may do, read Access policies; a client-side route guard is not a substitute for backend authorization.

Sign-in and multi-factor verification​

login() can return either an authenticated response or an MFA continuation. Handle the discriminant before treating the result as a completed session:

const result = await client.login(loginBody);

if ('nextStep' in result && result.nextStep === 'mfa') {
  const authenticated = await result.verify(oneTimeCode);
  await client.setActiveLogin(authenticated);
} else {
  await client.setActiveLogin(result);
}

Use the account's supported MFA method and show a clear retry path for an invalid or expired code. The server controls the allowed login methods and token lifetimes.

Registration is a multi-step flow​

register() may return a clinician-invite step when project configuration routes a registration through an invitation. registerPractitioner() is a separate practitioner self-registration method. Inspect the result before setting the active login; do not assume every registration response contains tokens.

Registration availability depends on project settings and the default practitioner access policy. Read project settings and the practitioner registration guide before enabling the flow.

When the backend intentionally uses a uniform “registration failed” result for an existing account, keep the UI message neutral. Do not reveal whether an email address has an account.

Session lifecycle​

const sessions = await client.getSessions();
await client.revokeSessions('other');
await client.logout();

logout() revokes the current server session and clears the local login even if the server cannot be reached. Token lifetimes are configured by the backend's ClientApplication. Pass Medplum's onUnauthenticated callback when the app needs to respond to an expired or unrecoverable session.

Password reset and external providers​

The SDK includes methods for starting and completing password recovery, changing a password, and signing in with Google or Apple. Provider configuration and project requirements live in Ovok Authentication; keep provider secrets on a trusted server and only expose the client identifier intended for the app.

Errors and throttling​

Authentication requests can be rate limited. Use isRateLimitError(error) and retryAfterMs to show a wait message. Use readOvokError(error) for stable status, code, and field errors; avoid branching on backend prose.