Overview

The Embedded Wallet Kit makes authentication incredibly simple. With just one function call, you can trigger a login or signup modal that automatically reflects the authentication methods you’ve configured in your Turnkey Dashboard. You can also call specific login and signup functions to create your own UI components and authentication flow.

Quick authentication

The easiest way to handle authentication is using the handleLogin function from the useTurnkey hook. This will automatically show a modal with all the authentication methods you’ve enabled in your dashboard.
page.tsx
"use client";
import { useTurnkey } from "@turnkey/react-wallet-kit";

function LoginButton() {
  const { handleLogin } = useTurnkey();
  return <button onClick={handleLogin}>Login / Sign Up</button>;
}
export default function Home() {
  return (
    <LoginButton /> 
  );
}
If you’re following our quick start guide, we can now view our button.
npm run dev
When a user clicks this button, they’ll see a modal with the authentication options you configured during the organization setup. Login modal showing authentication options

UI customization

Want to customize the look and feel of the authentication modal? You can learn more about customizing the UI components in the UI Customization section.

Without a modal

If you need more control over the authentication flow, you can also call specific login and signup functions individually, without showing a modal.
import { useTurnkey } from "@turnkey/react-wallet-kit";

function CustomAuthButtons() {
  const { loginWithPasskey, signUpWithPasskey } = useTurnkey();

  return (
    <div>
      <button onClick={loginWithPasskey}>Log in with Passkey</button>
      <button onClick={signUpWithPasskey}>Sign Up with Passkey</button>
    </div>
  );
}
For a complete list of available authentication functions, check out the SDK Reference.

Knowing when users are authenticated

To check if a user is authenticated, you can use the authState variable from the useTurnkey hook.
import { useTurnkey, AuthState } from "@turnkey/react-wallet-kit";

function AuthStatus() {
  const { authState, user, handleLogin } = useTurnkey();

  return (
    <div>
      {authState === AuthState.Authenticated ? (
        <p>Welcome back, {user?.userName}!</p>
      ) : (
        <button onClick={handleLogin}>Log in</button>
      )}
    </div>
  );
}
You can also set up an onAuthenticationSuccess callback passed in through the TurnkeyProvider to handle post-authentication logic, such as redirecting.
<TurnkeyProvider
  config={turnkeyConfig}
  callbacks={{
    onAuthenticationSuccess: ({ session }) => {
      console.log("User authenticated:", session);
      router.push("/dashboard");
    },
  }}
>
  {children}
</TurnkeyProvider>

Configuring OAuth

Using OAuth requires additional configuration. To start, ensure you enable OAuth and check the OAuth providers you want to use in the Wallet Kit section of the Turnkey Dashboard. See the Getting Started guide for more details. OAuth providers configuration Now, you must add your client IDs for each OAuth provider you want to use as well as a redirect URI in the TurnkeyProvider’s config. You can also toggle openOauthInPage to true if you want the OAuth flow to replace the current page instead of opening a new popup.
<TurnkeyProvider
  config={{
    authProxyConfigId: process.env.NEXT_PUBLIC_AUTH_PROXY_CONFIG_ID || "",
    organizationId: process.env.NEXT_PUBLIC_ORGANIZATION_ID || "",

    auth: {
      oauthConfig: {
        oauthRedirectUri: process.env.NEXT_PUBLIC_REDIRECT_URI || "", // Eg: "https://your-app.com/home". This must match the redirect URI configured in your OAuth provider's dashboard.
        openOauthInPage: false, // Set to true if you want OAuth to replace the current page instead of opening a new popup

        // You will typically get these from the OAuth provider's dashboard. Eg: Google developer console.
        googleClientId: process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID || "",
        appleClientId: process.env.NEXT_PUBLIC_APPLE_CLIENT_ID || "",
        facebookClientId: process.env.NEXT_PUBLIC_FACEBOOK_CLIENT_ID || "",
      },
    },
  }}
>
  {children}
</TurnkeyProvider>
You can retrieve the client IDs from the OAuth provider’s dashboard. Note that the redirect URI must match the one you configured in your TurnkeyProvider config. For example, for Google, you can create a web client ID in the Google developer console. The Google developer console Your “Log in or sign up” modal should now include the OAuth options you configured. Authentication modal with OAuth options

Customize sub-organization creation

Need to configure default user names, passkey names, wallet creations or anything sub-org related? You can learn more about customizing the sub-orgs you create in the Sub-Organization Customization section.

Next steps

Once your users are authenticated, you can start building embedded wallet functionality! Check out the Using Embedded Wallets guide to learn how to create and manage wallets in your React app.