Skip to content

Passkey Signup Authentication

Passkeys provide a secure, passwordless authentication method that can be used to create wallets for your users without going through email verification flows. You can implement passkey signup with or without an associated email address.

You can implement Passkey Signup authentication in two ways:

Pre-built UI Components

Account Kit provides pre-built UI components that handle the entire Passkey Signup authentication flow with minimal code.

Step 1: Add Authentication Components to Your Page

Before configuring your authentication, first add one of the pre-built components to your application:

Using Modal Authentication

To add authentication in a modal popup:

import React from "react";
import { useAuthModal } from "@account-kit/react";
 
export default function MyPage() {
  const { openAuthModal } = useAuthModal();
 
  return <button onClick={openAuthModal}>Sign in</button>;
}

For more details on modal configuration, see the Modal Authentication documentation.

Or:

Using Embedded Authentication

To embed authentication directly in your page:

import React from "react";
import { AuthCard } from "@account-kit/react";
 
export default function MyLoginPage() {
  return (
    <div className="flex flex-row p-4 bg-white border border-gray-200 rounded-lg">
      <AuthCard />
    </div>
  );
}

For more details on embedded authentication, see the Embedded Authentication documentation.

Step 2: Configure Passkey Signup in UI Components

After adding the components, configure the Passkey Signup authentication in your application config:

import { AlchemyAccountsUIConfig, createConfig } from "@account-kit/react";
import { sepolia, alchemy } from "@account-kit/infra";
 
const uiConfig: AlchemyAccountsUIConfig = {
  auth: {
    sections: [
      [
        // Include passkey in a section
        { type: "passkey" },
 
        // You can combine with other authentication methods
        { type: "email" },
      ],
    ],
    // Enable automatic passkey creation after signup
    addPasskeyOnSignup: true,
  },
};
 
export const config = createConfig(
  {
    transport: alchemy({ apiKey: "your-api-key" }),
    chain: sepolia,
  },
  uiConfig
);

Passkey signup configuration accepts the following options:

type PasskeyAuthType = {
  type: "passkey";
};

You can find the full type definition in the Account Kit source code.

The key configuration option for passkey signup is addPasskeyOnSignup: true, which will prompt users to create a passkey after they sign up with another method (like email).

For more details on UI component customization, see the UI Components documentation.

Custom UI

If you need complete control over the user experience, you can implement your own custom UI for Passkey Signup authentication using Account Kit hooks.

Option 1: Passkey Signup with Email (Recommended)

This approach associates an email with the passkey, allowing users to recover their account if they lose access to their device.

import { useAuthenticate } from "@account-kit/react";
 
// Inside your component
const { authenticate } = useAuthenticate();
 
// When the user submits their email and wants to create a passkey
const handlePasskeySignup = (email: string) => {
  // Important: Validate the email before proceeding
  if (!isValidEmail(email)) {
    // Handle validation error
    return;
  }
 
  authenticate(
    {
      type: "passkey",
      email,
    },
    {
      onSuccess: () => {
        // Success - passkey created and user authenticated
      },
      onError: (error) => {
        // Handle error
      },
    }
  );
};
 
// Simple email validation function
const isValidEmail = (email: string) => {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
};

Option 2: Passkey Signup without Email

This approach creates a passkey without an associated email. Use this only if you have another recovery mechanism in place.

import { useAuthenticate } from "@account-kit/react";
 
// Inside your component
const { authenticate } = useAuthenticate();
 
// When the user wants to create a passkey without email
const handlePasskeyOnlySignup = (username: string) => {
  authenticate(
    {
      type: "passkey",
      createNew: true,
      username, // A unique identifier for the passkey
    },
    {
      onSuccess: () => {
        // Success - passkey created and user authenticated
      },
      onError: (error) => {
        // Handle error
      },
    }
  );
};

Step 3: Track Authentication Status

Use the useSignerStatus hook to determine if the user is authenticated:

import { useSignerStatus } from "@account-kit/react";
 
// Inside your component
const { isConnected } = useSignerStatus();
 
// You can use isConnected to conditionally render UI