Overview The CrossmintAuthClient class provides client-side authentication functionality including OAuth, email OTP, Farcaster, and smart wallet authentication. It handles token management, automatic refresh, and secure storage of authentication credentials.
Installation npm install @crossmint/client-sdk-auth
Creating an Instance import { CrossmintAuthClient } from '@crossmint/client-sdk-auth' ; import { Crossmint } from '@crossmint/common-sdk-base' ; const crossmint = new Crossmint ({ apiKey: 'your-api-key' }); const authClient = CrossmintAuthClient . from ( crossmint , { callbacks: { onTokenRefresh : ( authMaterial ) => console . log ( 'Token refreshed' ), onLogout : () => console . log ( 'User logged out' ) }, logoutRoute: '/api/auth/logout' , refreshRoute: '/api/auth/refresh' });
Configuration config
CrossmintAuthClientConfig
Configuration object for the auth client Lifecycle callbacks for authentication events onTokenRefresh
(authMaterial: AuthMaterialWithUser) => void
Called when the JWT is refreshed
Called when the user logs out
Custom server endpoint for handling logout. If not provided, uses default Crossmint logout endpoint.
Custom server endpoint for refreshing tokens. If not provided, uses default Crossmint refresh endpoint.
Custom storage provider for tokens. Defaults to browser cookies/localStorage.
Methods getUser Retrieves the currently authenticated user’s information.
const user = await authClient . getUser (); console . log ( user . email , user . id );
Returns: Promise<User>Throws: CrossmintAuthenticationError if the user is not authenticated or request failsgetOAuthUrl Generates an OAuth URL for the specified provider.
const oauthUrl = await authClient . getOAuthUrl ( 'google' , { appSchema: 'myapp://' }); window . location . href = oauthUrl ;
OAuth provider: 'google', 'twitter', 'facebook', etc.
Custom app schema for mobile deep linking
Returns: Promise<string> - The OAuth authorization URLThrows: CrossmintAuthenticationError if the origin is unauthorized or request failssendEmailOtp Sends a one-time password to the specified email address.
const result = await authClient . sendEmailOtp ( '[email protected] ' ); console . log ( 'Email ID:' , result . emailId );
Email address to send the OTP to
Returns: Promise<{ emailId: string }> - Contains the email ID needed for confirmationThrows: CrossmintAuthenticationError if sending failsconfirmEmailOtp Confirms an email OTP and completes authentication.
const oneTimeSecret = await authClient . confirmEmailOtp ( '[email protected] ' , emailId , '123456' );
Email address that received the OTP
Email ID returned from sendEmailOtp
Returns: Promise<string> - One-time secret for completing authenticationThrows: CrossmintAuthenticationError if verification failssignInWithFarcaster Authenticates a user using Farcaster.
import { useSignIn } from '@farcaster/auth-kit' ; const { signIn , data } = useSignIn (); await signIn (); if ( data ) { const oneTimeSecret = await authClient . signInWithFarcaster ( data ); }
Farcaster sign-in data from @farcaster/auth-kit
Returns: Promise<string> - One-time secret for completing authenticationThrows: CrossmintAuthenticationError if authentication failssignInWithSmartWallet Initiates smart wallet authentication by requesting a signature challenge.
const { message , nonce } = await authClient . signInWithSmartWallet ( '0x1234...5678' , 'evm' ); // Sign the message with the wallet const signature = await wallet . signMessage ( message ); // Complete authentication await authClient . authenticateSmartWallet ( '0x1234...5678' , 'evm' , signature );
Returns: Promise<{ message: string; nonce: string }> - Challenge data to signThrows: CrossmintAuthenticationError if request failsauthenticateSmartWallet Completes smart wallet authentication with a signed message.
const result = await authClient . authenticateSmartWallet ( '0x1234...5678' , 'evm' , signature );
Signed message from the wallet
Returns: Promise<{ oneTimeSecret: string }> - One-time secret for session establishmentThrows: CrossmintAuthenticationError if authentication failshandleRefreshAuthMaterial Manually triggers token refresh. This is automatically scheduled before token expiration.
const authMaterial = await authClient . handleRefreshAuthMaterial ();
Custom refresh token secret. If not provided, uses stored token.
Returns: Promise<AuthMaterialWithUser | null> - New auth material or null if refresh failslogout Logs out the current user and clears all stored credentials.
await authClient . logout ();
Returns: Promise<void>Types AuthMaterialWithUser interface AuthMaterialWithUser { jwt : string ; refreshToken : { secret : string ; expiresAt : string ; }; user : { id : string ; email ?: string ; userId : string ; }; }
OAuthProvider type OAuthProvider = 'google' | 'twitter' | 'facebook' | 'discord' | 'apple' ;
Error Handling import { CrossmintAuthenticationError } from '@crossmint/common-sdk-auth' ; try { await authClient . sendEmailOtp ( email ); } catch ( error ) { if ( error instanceof CrossmintAuthenticationError ) { console . error ( 'Auth error:' , error . message ); } }
Best Practices
Token Refresh : The client automatically refreshes tokens before expiration. Don’t manually refresh unless necessary.Storage : Use custom storage providers for React Native or other non-browser environments.Error Handling : Always handle CrossmintAuthenticationError for authentication failures.Server Routes : For Next.js or other server frameworks, provide custom refreshRoute and logoutRoute for secure cookie handling.
Example: Complete Email OTP Flow import { CrossmintAuthClient } from '@crossmint/client-sdk-auth' ; const authClient = CrossmintAuthClient . from ( crossmint , { callbacks: { onTokenRefresh : ( authMaterial ) => { console . log ( 'Session refreshed' ); } } }); // Step 1: Send OTP const { emailId } = await authClient . sendEmailOtp ( '[email protected] ' ); // Step 2: User enters code from email const otpCode = '123456' ; // From user input // Step 3: Verify OTP const oneTimeSecret = await authClient . confirmEmailOtp ( '[email protected] ' , emailId , otpCode ); // Step 4: Get user info const user = await authClient . getUser (); console . log ( 'Logged in as:' , user . email );