How to Use Better Auth in Ionic and Capacitor Apps¶

Better Auth is an open-source, framework-agnostic authentication framework for TypeScript. Whether you're building with Ionic, Angular, React, or Vue, the Better Auth JavaScript SDK works out of the box in your Capacitor app — no special configuration needed. Since Capacitor apps are essentially web apps running in a native WebView, you can use the SDK directly for standard authentication flows. You only need Capacitor plugins when it comes to social login flows that require native functionality, like opening a browser window or using platform-specific sign-in APIs. This guide shows you how to set up mobile authentication with Better Auth in your Capacitor app using the Apple Sign-In, Google Sign-In, and OAuth plugins.

Build and deploy your Capacitor app with Capawesome Cloud

Prerequisites¶

Before you begin, make sure you have the following:

A Better Auth backend set up and running. If you don't have one yet, follow the official installation guide to get started.
A Capacitor app ready for development.

Setting Up the Auth Client¶

First, install the Better Auth client SDK in your Capacitor app:

npm install better-auth

Then create an auth client instance pointing to your Better Auth backend:

import { createAuthClient } from "better-auth/client";

const authClient = createAuthClient({
  baseURL: "https://api.example.com",
});

That's it. Since your Capacitor app runs in a WebView, the Better Auth client works exactly the same as in any other web application.

Email and Password Authentication¶

Email and password authentication works without any additional plugins. The Better Auth client handles everything over HTTP, which the WebView supports natively.

Signing Up¶

Use authClient.signUp.email() to create a new account:

const { data, error } = await authClient.signUp.email({
    name: "John Doe",
    email: "john.doe@example.com",
    password: "password1234",
    image: "https://example.com/image.png",
    callbackURL: "https://example.com/callback",
});

Signing In¶

Use authClient.signIn.email() to sign in with an existing account:

const { data, error } = await authClient.signIn.email({
    email: "john.doe@example.com",
    password: "password1234",
});

Both methods return a { data, error } object, making it easy to handle success and failure cases in your UI.

While email and password authentication works directly through the SDK, social login providers like Apple, Google, or Microsoft typically require opening a browser window or using platform-specific APIs for mobile authentication. This is where Capacitor plugins come in.

The approach is simple: use a Capacitor plugin to handle the native social login flow and obtain an ID token, then pass that token to Better Auth's signIn.social() method. This gives you a native sign-in experience while Better Auth manages your users and sessions on the server.

The Apple Sign-In plugin provides native Sign in with Apple on Android, iOS, and web. To install the plugin, please refer to the Installation section in the plugin documentation.

Use signIn(...) to obtain an ID token and pass it to Better Auth:

import { AppleSignIn, SignInScope } from "@capawesome/capacitor-apple-sign-in";

const signInWithApple = async () => {
    // 1. Sign in with Apple using the plugin to get an ID token
    const { idToken } = await AppleSignIn.signIn({
        redirectUrl: 'https://example.com/callback', // Only required on Android and Web
        scopes: [SignInScope.Email, SignInScope.Name],
    });
    // 2. Pass the ID token to Better Auth to sign in or create the user
    await authClient.signIn.social({
        provider: "apple",
        idToken: {
            token: idToken,
        },
    });
};

The plugin handles the native Apple sign-in dialog on iOS and falls back to a web-based flow on Android and web. The returned idToken is a JWT that Better Auth verifies server-side to create or sign in the user.

The Google Sign-In plugin provides native Google Sign-In on Android, iOS, and web. To install the plugin, please refer to the Installation section in the plugin documentation.

Use signIn(...) to obtain an ID token and pass it to Better Auth:

import { GoogleSignIn } from "@capawesome/capacitor-google-sign-in";

const signInWithGoogle = async () => {
    // 1. Sign in with Google using the plugin to get an ID token
    const { idToken } = await GoogleSignIn.signIn({
        redirectUrl: 'https://example.com/callback', // Only required on Android and Web
        scopes: ["profile", "email"],
    });
    // 2. Pass the ID token to Better Auth to sign in or create the user
    await authClient.signIn.social({
        provider: "google",
        idToken: {
            token: idToken,
        },
    });
};

On Android, the plugin uses the Credential Manager API for a seamless sign-in experience. On iOS, it uses the Google Sign-In SDK. The returned idToken is passed to Better Auth just like with Apple.

Other Providers with the OAuth Plugin¶

For providers that don't have a dedicated plugin — like Microsoft, LinkedIn, Facebook, or PayPal — you can use the OAuth plugin. It supports any OAuth 2.0 / OpenID Connect provider using the Authorization Code flow with PKCE. To install the plugin, please refer to the Installation section in the plugin documentation.

Here's an example of signing in with Microsoft using login(...):

import { Oauth } from "@capawesome-team/capacitor-oauth";

const signInWithMicrosoft = async () => {
    // 1. Use the OAuth plugin to sign in with Microsoft and get an ID token
    const result = await Oauth.login({
        issuerUrl: 'https://login.microsoftonline.com/{tenant-id}/v2.0',
        clientId: '{client-id}',
        redirectUrl: 'com.example.app://oauth/callback',
        scopes: ['openid', 'profile', 'email'],
    });
    // 2. Pass the ID token to Better Auth to sign in or create the user
    await authClient.signIn.social({
        provider: "microsoft",
        idToken: {
            token: result.idToken,
        },
    });
};

The OAuth plugin handles the browser-based authorization flow and returns an ID token, which you then pass to Better Auth. This same approach works for any provider that Better Auth supports, including LinkedIn, Facebook, PayPal, and many more.

Stay Updated¶

If you want to stay up to date with the latest news and updates from Capawesome, subscribe to the newsletter:

Subscribe to the Capawesome Newsletter

Conclusion¶

Integrating Better Auth into a Capacitor app is straightforward. Since Capacitor apps run in a WebView, the Better Auth JavaScript SDK works out of the box for authentication flows like email and password. For social sign-in, the Apple Sign-In, Google Sign-In, and OAuth plugins handle the native parts and return ID tokens that Better Auth verifies server-side — giving you a seamless authentication experience across Android, iOS, and web.

If you want to learn more about OAuth-based authentication in Capacitor apps, check out the guide on How to Sign In with Auth0 Using Capacitor. If you have any questions, join the Capawesome Discord server and connect with the community. To stay updated on the latest news, subscribe to the Capawesome newsletter.