Getting started with authentication

Account Kit makes it really easy to authenticate your users using a number of different authentication methods. If you followed the quickstart, then your app is already setup to authenticate users and you can skip this guide!

Implementation Options

For each authentication method, you have two implementation options:

  1. Pre-built UI Components - Ready-to-use components that handle the entire authentication flow with minimal code and customizable styling.

  2. Custom UI with React Hooks - Build your own UI components using our React hooks for complete control over the user experience.

Authentication Methods

Account Kit supports several authentication methods:

Setup

If you haven’t followed the quickstart guide, make sure to set up the following first:

  1. Get your API key by creating a new app in your Alchemy Dashboard

    Make sure your desired network is enabled for your app under the Networks tab.

  2. Create a new account config in your Account Kit Dashboard

    1. Apply the config to your app from step 1

      apply your the config to the app from the first step
    2. Enable authentication methods you want to support.


      Email auth

      If you want to use email auth, toggle on email.

      • For testing, use http://localhost:3000 as the Redirect URL (Note http not https)
      • The user will be redirected to the Redirect URL if you use the magic link email flow
      • Optionally stylize ✨ the email with your brand color and logo!
      configure email auth
      Social auth

      If you want to enable social login, toggle which auth providers you want to support.

      • For testing, add http://localhost:3000 as a whitelisted origin

      • Add the link that your dapp will be running on to the whitelisted origin list

      • Optionally enter your own OAuth credentials or use our defaults

        configure social auth
  3. Create the config and copy the API Key

    how to copy the api key

…and paste the API key into your app’s config.ts

import { 
type AlchemyAccountsUIConfig = { auth?: { addPasskeyOnSignup?: boolean; header?: React.ReactNode; hideError?: boolean; onAuthSuccess?: () => void; sections: AuthType[][]; hideSignInText?: boolean; }; illustrationStyle?: "outline" | "linear" | "filled" | "flat" | undefined; modalBaseClassName?: string; supportUrl?: string | undefined; }
AlchemyAccountsUIConfig
,
const createConfig: (props: CreateConfigProps, ui?: AlchemyAccountsUIConfig) => AlchemyAccountsConfigWithUI

Wraps the createConfig that is exported from @aa-sdk/core to allow passing an additional argument, the configuration object for the Auth Components UI (the modal and AuthCard).

createConfig
} from "@account-kit/react";
import {
const sepolia: Chain
sepolia
,
function alchemy(config: AlchemyTransportConfig): AlchemyTransport

Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.

alchemy
} from "@account-kit/infra";
// Define UI configuration for authentication components // See individual login method pages for detailed configuration options const
const uiConfig: AlchemyAccountsUIConfig
uiConfig
:
type AlchemyAccountsUIConfig = { auth?: { addPasskeyOnSignup?: boolean; header?: React.ReactNode; hideError?: boolean; onAuthSuccess?: () => void; sections: AuthType[][]; hideSignInText?: boolean; }; illustrationStyle?: "outline" | "linear" | "filled" | "flat" | undefined; modalBaseClassName?: string; supportUrl?: string | undefined; }
AlchemyAccountsUIConfig
= {
auth?: { addPasskeyOnSignup?: boolean; header?: React.ReactNode; hideError?: boolean; onAuthSuccess?: () => void; sections: AuthType[][]; hideSignInText?: boolean; } | undefined
auth
: {
sections: AuthType[][]

Each section can contain multiple auth types which will be grouped together and separated by an OR divider

sections
: [
[ // Example: Email OTP authentication {
type: "email"
type
: "email",
emailMode?: "magicLink" | "otp" | undefined
emailMode
: "otp",
}, // You can add more authentication methods here // See login method pages for available options ], ], }, }; export const
const config: AlchemyAccountsConfigWithUI
config
=
function createConfig(props: CreateConfigProps, ui?: AlchemyAccountsUIConfig): AlchemyAccountsConfigWithUI

Wraps the createConfig that is exported from @aa-sdk/core to allow passing an additional argument, the configuration object for the Auth Components UI (the modal and AuthCard).

createConfig
(
{
transport: AlchemyTransport
transport
:
function alchemy(config: AlchemyTransportConfig): AlchemyTransport

Creates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.

alchemy
({
apiKey: string
apiKey
: "ALCHEMY_API_KEY" }), // TODO: add your Alchemy API key - https://dashboard.alchemy.com/accounts
chain: Chain
chain
:
const sepolia: Chain
sepolia
,
ssr?: boolean | undefined

Enable this parameter if you are using the config in an SSR setting (eg. NextJS) Turing this setting on will disable automatic hydration of the client store

ssr
: true, // more about ssr: https://www.alchemy.com/docs/wallets/react/ssr
enablePopupOauth: true
enablePopupOauth
: true, // must be set to "true" if you plan on using popup rather than redirect in the social login flow
// For more about persisting state with cookies, see: https://www.alchemy.com/docs/wallets/react/ssr#persisting-the-account-state // storage: cookieStorage, },
const uiConfig: AlchemyAccountsUIConfig
uiConfig
,
);

What’s next?

Now you can choose which authentication methods you want to implement and how you want to implement them:

  1. Using our Pre-built UI components to handle the entire authentication flow with minimal code.
  2. Using our React hooks to build your own custom UI for complete control.

Each authentication method has dedicated documentation for both implementation approaches.

Enhancing Security with Multi-Factor Authentication

After implementing your chosen authentication methods, you can add an extra layer of security by enabling multi-factor authentication (MFA):

You can enable multi-factor authentication (MFA) via authenticator apps (TOTP). These generate time-based one-time passcodes in an app like Google Authenticator or Authy. When users log in via Email OTP, Magic Link, or Social Login, they’ll be prompted for their 6-digit TOTP code if MFA is enabled.

Multi-factor authentication significantly improves account security by requiring users to verify their identity using both their primary authentication method and a time-based code from an authenticator app.