Custom Authentication UI with React Hooks

This guide covers building custom authentication UI using Para’s React hooks from @getpara/react-sdk@alpha. This approach provides simplified state management and is recommended for most React applications.

For maximum control over authentication flow and custom React Query implementations, see the Para Client Approach.

Prerequisites

You must have a Para account set up with authentication methods enabled in your Developer Portal. Install the React SDK:

npm install @getpara/react-sdk@alpha --save-exact

Authentication States

There are three stages for an authenticating user and three corresponding AuthState types that are returned from various authentication methods:

Stage	Meaning	Applicable Methods
`'verify'`	The user is using basic authentication and must authenticate via the returned `loginUrl`. Or the user is using a legacy auth method, has entered their email or phone number and been sent a confirmation code via email or SMS. Alternatively, they have logged in via an external wallet and need to sign a message to verify their ownership of the wallet.	`signUpOrLogIn`, `loginExternalWallet`
`'signup'`	The user has verified their email, phone number, external wallet, or completed a third-party authentication and may now create a WebAuth passkey or password to secure their account.	`verifyNewAccount`, `verifyExternalWallet`, `verifyOAuth`, `verifyTelegram`, `verifyFarcaster`
`'login'`	The user has previously signed up and can now log in using their WebAuth passkey or password.	`signUpOrLogIn` , `loginExternalWallet` , `verifyOAuth` , `verifyTelegram`, `verifyFarcaster`
`'done'`	The user is using basic authentication and has completed the process.	`verifyOAuth`, `verifyTelegram`, `verifyFarcaster`

AuthState Type Definitions

Authentication State Management

You will most likely want to track the AuthState within your app and update it with each method resolution. For example, you may want to store it in a dedicated context:

import React from 'react';
import { AuthState } from '@getpara/react-sdk';

const AuthStateContext = React.createContext<[
  AuthState | undefined,
  React.Dispatch<React.SetStateAction<AuthState | undefined>>
]>([undefined, () => {}]);

export function AuthStateProvider({ children }: React.PropsWithChildren) {
  const [authState, setAuthState] = React.useState<AuthState | undefined>();
  
	return {
		<AuthStateContext.Provider value={[authState, setAuthState]}>
		  {children}
		</AuthStateContext.Provider>
	};
}

export const useAuthState = () => React.useContext(AuthStateContext);

Authentication Hooks

Phone or Email Authentication

To authenticate a user via email or phone number, use the useSignUpOrLogIn hook. This mutation will either fetch the user with the provided authentication method and, for basic auth users, return an AuthStateVerify object or, for passkey, password and PIN users, return an AuthStateLogin object, or create a new user and return an AuthStateVerify object.

If the user already exists they can be in one of two states:
1. Basic auth users: An AuthStateVerify state is returned with a nextStage value of login and a loginUrl that should be opened for the user to authenticate in the Para Portal.
2. Passkey, password, PIN users: An AuthStateLogin state is returned with a combination of passkeyUrl, passwordUrl or pinUrl that should be opened in a new window or tab.
- Once one of these URLs are opened, invoke the useWaitForLogin mutation. This hook will wait until the user has completed the login process in the new window and then perform any needed setup.
If the user is new, an AuthStateVerify state is returned with a nextStage value of signup and the user can be handled one of two ways:
1. Basic auth users: A loginUrl is returned on the AuthStateVerify object that should be opened for the user to complete sign up in the Para Portal. Once this url is opened, invoke the useWaitForWalletCreation or useWaitForSignup mutation. This hook will wait until the user has completed the signup process in the new window and then perform any needed setup.
2. Passkey, password, PIN users: No loginUrl is returned, and the user should be prompted to enter the one-time code they received via email or SMS and that code should be verified using the useVerifyNewAccount hook.

import { useSignUpOrLogIn } from "@getpara/react-sdk@alpha";
import { useAuthState } from '@/hooks';

function AuthInput() {
  const { signUpOrLogIn, isLoading, isError } = useSignUpOrLogIn();
  const [authState, setAuthState] = useAuthState();
 
  const [authType, setAuthType] = useState<'email' | 'phone'>("email");

  const onSubmit = (identifier: string) => {
    signUpOrLogIn(
      {
        auth: authType === "email"
            ? { email: identifier }
            : { phone: identifier as `+${number}` },
      },
      {
        onSuccess: (authState) => {
          setAuthState(authState);
       
          switch (authState.stage) {
            case "verify":
              // Initiate polling based on what the next stage will be
              if (authState.nextStage === 'signup') {
                // Trigger the waitForWalletCreation or waitForSignup mutations here or once the loginUrl is opened
              } else if (authState.nextStage === 'login') {
                // Trigger the waitForLogin mutation here or once the loginUrl is opened
              }

              if(authState.loginUrl) {
                // Open the loginUrl in a new window or tab for basic auth users
              } else {
                // Display verification code input
              }
              break;
            case "login":
              const { passkeyUrl, passwordUrl, pinUrl } = authState;
              // Open a login URL in a new window or tab
              // Trigger the waitForLogin mutation here or once one of the URLs are opened
              break;
          }
        },
        onError: (error) => {
          // Handle error
        },
      }
    );
  };

  // ...
}

Verify new account

Not applicable to basic auth users

While in the verify stage for passkey, password or PIN users, you will need to display an input for a six-digit code and a callback that invokes the useVerifyNewAccount hook. This will validate the one-time code and, if successful, will return an AuthStateSignup object. (The email or phone number previously entered is now stored, and will not need to be resupplied.)

import { useVerifyNewAccount } from "@getpara/react-sdk@alpha";
import { useAuthState } from '@/hooks';

function VerifyOtp() {
  const { verifyNewAccount, isLoading, isError } = useVerifyNewAccount();
  const [_, setAuthState] = useAuthState();
  
  const [verificationCode, setVerificationCode] = useState('');

  const onSubmit = (verificationCode: string) => {
    verifyNewAccount(
      { verificationCode },
      {
        onSuccess: (authState) => {
          setAuthState(authState);
     
          const { isPasskeySupported, passkeyUrl, passwordUrl, pinUrl } = authState;
         
          // Update your UI and prepare to log in the user
        },
        onError: (error) => {
          // Handle a mismatched code
        },
      }
    );
  };

  // ...
}

Resend verification code

Not applicable to basic auth users

You can present a button to resend the verification code to the user’s email or phone in case they need a second one.

import { useResendVerificationCode } from "@getpara/react-sdk@alpha";

function VerifyOtp() {
  const { resendVerificationCode, isLoading, isError } = useResendVerificationCode();
  const [isResent, setIsResent] = React.useState(false);
  const timeout = useRef();
  
  const onClickResend = () => {
    resendVerificationCode(
      undefined,
      {
        onSuccess: () => {
          setIsResent(true);
          
          timeout.current = setTimeout(() => {
            setIsResent(false);
          }, 3000)
        },
        onError: e => {
          console.error(e);
        }
      }
    );
  }
  
  // ...
}

Basic auth users After the signUpOrLogIn process is complete, you will receive an AuthStateVerify object with a nextStage value of signup and a loginUrl. For compatibility and security, you will most likely want to open this URL in a new popup window, and then immediately invoke the useWaitForWalletCreation hook. This will wait for the user to complete signup and then create a new wallet for each wallet type you have configured in the Para Developer Portal. If you would like more control over the signup process, you can also call the useWaitForSignup hook, which will resolve after signup but bypass automatic wallet provisioning. To cancel the process in response to UI events, you can pass the isCanceled callback. Passkey, password, PIN users After verifyNewAccount process is complete, you will receive an AuthStateSignup object. Depending on your configuration, the AuthStateSignup will contain a Para URL for creating a WebAuth biometric passkey, a Para URL for creating a new password, or both. For compatibility and security, you will most likely want to open these URLs in a new popup window, and then immediately invoke the useWaitForWalletCreation hook. This will wait for the user to complete signup and then create a new wallet for each wallet type you have configured in the Para Developer Portal. If you would like more control over the signup process, you can also call the useWaitForSignup hook, which will resolve after signup but bypass automatic wallet provisioning. To cancel the process in response to UI events, you can pass the isCanceled callback.

import { useWaitForWalletCreation } from "@getpara/react-sdk@alpha";
import { useAuthState } from '@/hooks';

function Signup() {
  const popupWindow = React.useRef<Window | null>(null);
  const { waitForWalletCreation, isLoading, isError } = useWaitForWalletCreation();
  const [authState, setAuthState] = useAuthState();
  
  // Invoke using the `loginUrl` for basic auth users or `passkeyUrl`, `passwordUrl` or `pinUrl` for passkey/password/PIN users
  const onSelectSignupMethod = (url: string) => {    
    popupWindow.current = window.open(url, `ParaSignup_${chosenMethod}`);
    
    waitForWalletCreation(
      {
        isCanceled: () => popupWindow.current?.closed,
      },
      {
        onSuccess: () => {
          // Handle successful signup and wallet provisioning
        },
        onError: (error) => {
          // Handle a canceled signup
        },
      }
    );
  };

  // ...
}

Log in an existing user

Basic auth users After the signUpOrLogIn process is complete, you will receive an AuthStateVerify object with a nextStage value of login and a loginUrl. For compatibility and security, you will most likely want to open this URL in a new popup window, and then immediately invoke the useWaitForLogin hook. This will wait for the user to complete the login process and resolve when it is finished. To cancel the process in response to UI events, you can pass the isCanceled callback. Passkey, password, PIN users After the signUpOrLogIn process is complete, you will receive an AuthStateLogin object. Depending on the users configuration, the AuthStateLogin will contain a Para URL for creating a WebAuth biometric passkey, a Para URL for creating a new password, or both. For compatibility and security, you will most likely want to open these URLs in a new popup window, and then immediately invoke the useWaitForLogin hook. This will wait for the user to complete the login process and resolve when it is finished. To cancel the process in response to UI events, you can pass the isCanceled callback.

import { useWaitForLogin } from "@getpara/react-sdk@alpha";
import { useAuthState } from '@/hooks';

function Login() {
  const popupWindow = React.useRef<Window | null>(null);
  const { waitForLogin, isLoading, isError } = useWaitForLogin();
  const [authState, setAuthState] = useAuthState();
  
  // Invoke using the `loginUrl` for basic auth users or `passkeyUrl`, `passwordUrl` or `pinUrl` for passkey/password/PIN users
  const onSelectLoginMethod = (url: string) => {
    popupWindow.current = window.open(url, 'ParaLogin');
    
    waitForLogin(
      {
        isCanceled: () => popupWindow.current?.closed,
      },
      {
        onSuccess: (result) => {
          const { needsWallet } = result;
          
          if (needsWallet) {
            // Create wallet(s) for the user if needed
          } else {
            // Set up signed-in UI
          }
                 },
        onError: (error) => {
          // Handle a canceled login
        },
      }
    );
  };

  // ...
}

Third-Party Authentication Hooks

OAuth

Para supports OAuth 2.0 sign-ins via Google, Apple, Facebook, Discord, and X, provided the linked account has an email address set. Once a valid email account is fetched, the process is identical to that for email authentication, simply bypassing the one-time code verification step. To implement OAuth flow, use the useVerifyOAuth hook.

import { type TOAuthMethod, useVerifyOAuth } from "@getpara/react-sdk@alpha";
import { useAuthState } from '@/hooks';

function OAuthLogin() {
  const popupWindow = React.useRef<Window | null>(null);
  const { verifyOAuth, isLoading, isError } = useVerifyOAuth();
  const [authState, setAuthState] = useAuthState();
  
  const onOAuthLogin = (method: TOAuthMethod) => {
    verifyOAuth(
      {
        method,
        onOAuthPopup: (oAuthPopup) => {
	        popupWindow.current = oAuthPopup;
        },
        isCanceled: () => popupWindow.current?.closed,
      },
      {
        onSuccess: (authState) => {
          setAuthState(authState);
          
          switch (authState.stage) {
            case 'signup':
              // New user: refer to 'Sign up a new user'
              break;
            case 'login':
              // Returning user: refer to 'Log in an existing user'
              break;
          };
        },
        onError: (error) => {
          // Handle a canceled OAuth verification
        },
      }
    );
  };

  // ...
}

To implement your own Telegram authentication flow, please refer to the official documentation. Para uses the following bots to handle authentication requests:

Environment	Username	Bot ID
`BETA`	@para_oauth_beta_bot	7788006052
`PROD`	@para_oauth_bot	7643995807

Once a Telegram authentication response is received, you can invoke the useVerifyTelegram hook to sign up or log in a user associated with the returned Telegram user ID. Users created via Telegram will not have an associated email address or phone number.

import { useVerifyTelegram } from "@getpara/react-sdk@alpha";
import { useAuthState } from '@/hooks';

type TelegramAuthObject = {
  auth_date: number;
  first_name?: string;
  hash: string;
  id: number;
  last_name?: string;
  photo_url?: string;
  username?: string;
};

function TelegramLogin() {
  const popupWindow = React.useRef<Window | null>(null);
  const { verifyTelegram, isLoading, isError } = useVerifyTelegram();
  const [authState, setAuthState] = useAuthState();
  
  const onTelegramResponse = (response: TelegramAuthObject) => {
    verifyTelegram(
      { telegramAuthObject: response },
      {
        onSuccess: (authState) => {
          setAuthState(authState);
          
          switch (authState.stage) {
            case 'signup':
              // New user: refer to 'Sign up a new user'
              break;
            case 'login':
              // Returning user: refer to 'Log in an existing user'
              break;
          };
        },
        onError: (error) => {
          // Handle a failed Telegram verification
        },
      }
    );
  };

  // ...
}

Farcaster

Refer to the official documentation for information on Farcaster’s SIWF (Sign In with Farcaster) feature. To use this authentication method, use the useVerifyFarcaster hook. The hook will supply a Farcaster Connect URI, which should be displayed to your users as a QR code. Like with Telegram, users created via Farcaster will not have an associated email address or phone number.

import { useVerifyFarcaster } from "@getpara/react-sdk@alpha";
import { useAuthState } from '@/hooks';

function FarcasterLogin() {
  const { verifyFarcaster, isLoading, isError } = useVerifyFarcaster();
  const [authState, setAuthState] = useAuthState();
  
  const [farcasterConnectUri, setFarcasterConnectUri] = useState<string | null>(null);
  const isCanceled = React.useRef(false);
  
  useEffect(() => {
    isCanceled.current = !farcasterConnectUri;
  }, [farcasterConnectUri]);
  
  const onClickCancelButton = () => {
    setFarcasterConnectUri(null);
  }
  
  const onClickFarcasterLoginButton = () => {
    verifyFarcaster(
      {
        onConnectUri: connectUri => {
	        setFarcasterConnectUri(connectUri);
	      },
	      isCanceled: () => isCanceled.current,
	    },
      {
        onSuccess: (authState) => {
          setAuthState(authState);
          
          switch (authState.stage) {
            case 'signup':
              // New user: refer to 'Sign up a new user'
              break;
            case 'login':
              // Returning user: refer to 'Log in an existing user'
              break;
          };
        },
        onError: (error) => {
          // Handle a failed Telegram verification
        },
      }
    );
  };

  // ...
}

Two-Factor Authentication Hooks

Para supports two-factor authentication via one-time codes in Google Authenticator or similar apps. To check a user’s current 2FA status, use the useSetup2fa hook:

If the user has already set up two-factor authentication, the setup2fa mutation will return { isSetup: true }.
If not, the mutation will return { isSetup: false, uri: string }, where uri is a URI that can be scanned as a QR code by Authenticator or a similar app.
When the user has entered the code from their authenticator app, you can use the useEnable2fa hook to activate 2FA for their account.
Subsequently, you can use the useVerify2fa hook to verify the user’s account by their one-time code.

import { useSetup2fa } from '@getpara/react-sdk';

function Setup2fa() {
  const { setup2fa, isPending } = useSetup2fa();
  const [twoFAUri, setTwoFAUri] = useState<string | null>(null);
  
  const onClickSetup2fa = () => {
    setup2fa(
      undefined,
      {
        onSuccess: (result) => {
          if (result.isSetup) {
            // User has already set up 2FA
          } else {
            // Display QR code with result.uri
            setTwoFAUri(result.uri);
          }
        },
        onError: (error) => {
          // Handle error
        },
      }
    );
  };
  
  // ...
}

Logout

To sign out the current user, use the useLogout hook. By default, signing out will preserve any pregenerated wallets (including guest login wallets) present in the device storage, some of which may not belong to the signed-in user. To clear all wallets, set the clearPregenWallets parameter to true.

import { useLogout } from '@getpara/react-sdk';

function Account() {
	const { logout, isPending } = useLogout();

  const onClickLogout = () => {
	  logout(
	    undefined,
      {
        onSuccess: () => {
          // Update UI to non-authenticated state
        },
      }
	  );
  };
  
  const onClickLogoutAndClearWallets = () => {
    logout(
	    { clearPregenWallets: true },
      {
        onSuccess: () => {
          // Update UI to non-authenticated state
        },
      }
	  );
  };
  
  // ...
}

Start Your Integration

Set Up Your Framework

Sign Transactions & Messages

Configure Wallets

Manage Sessions

Customize Your Integration

Build with Hooks

Troubleshooting

Custom Authentication UI with React Hooks

Prerequisites

Authentication States

AuthState Type Definitions

Authentication State Management

Authentication Hooks

Phone or Email Authentication

Verify new account

Resend verification code

Log in an existing user

Third-Party Authentication Hooks

OAuth

Telegram

Farcaster

Two-Factor Authentication Hooks

Logout

Next Steps

Para Client Approach

Session Management

Start Your Integration

Set Up Your Framework

Sign Transactions & Messages

Configure Wallets

Manage Sessions

Customize Your Integration

Build with Hooks

Troubleshooting

​Prerequisites

​Authentication States

​AuthState Type Definitions

​Authentication State Management

​Authentication Hooks

​Phone or Email Authentication

​Sign up or log in

​Verify new account

​Resend verification code

​Sign up a new user

​Log in an existing user

​Third-Party Authentication Hooks

​OAuth

​Telegram

​Farcaster

​Two-Factor Authentication Hooks

​Logout

​Next Steps

Para Client Approach

Session Management

Prerequisites

Authentication States

AuthState Type Definitions

Authentication State Management

Authentication Hooks

Phone or Email Authentication

Sign up or log in

Verify new account

Resend verification code

Sign up a new user

Log in an existing user

Third-Party Authentication Hooks

OAuth

Telegram

Farcaster

Two-Factor Authentication Hooks

Logout

Next Steps