Skip to main content

Authentication Integration Guide

Crossmint provides a comprehensive user management solution tightly integrated with all other Crossmint products. Authenticate users using Web3 or traditional sign-in methods, with seamless wallet creation and unified identity management.

Why this matters:

  • Unified identity system: Single user account across your backend and Web3 app
  • Multiple auth methods: Email OTP, social logins, wallet connections, and Farcaster
  • Automatic wallet creation: Optionally create or link wallets with user accounts
  • Drag and drop integration: Setup in under 5 minutes

🎯 Available Authentication Methods​

1. Email OTP Authentication​

Passwordless sign-in using one-time codes delivered to the user's email.

  • No passwords required
  • Secure and user-friendly
  • Automatic account creation

2. Social Account Authentication​

Sign in with popular social platforms:

  • Google
  • Apple
  • X (Twitter)
  • And more

3. Farcaster Integration​

Using the Sign In With Farcaster (SIWF) standard

  • Web3-native authentication
  • Decentralized identity support

4. External Wallet Authentication​

Connect with crypto wallets for Web3 authentication:

  • MetaMask
  • WalletConnect
  • Flow wallets
  • And other Web3 wallets

Prerequisites​

Make sure you have:

Crossmint account:

React/Next.js project:

  • React 16.8+ or Next.js 13+
  • TypeScript support (recommended)

Technical knowledge:

  • Basic React hooks and state management
  • Understanding of authentication flows

Quick Start (5 minutes)​

Step 1: Install the SDK​


_10
npm i @crossmint/client-sdk-react-ui

Step 2: Add Crossmint Providers​


_17
"use client";
_17
_17
import {
_17
CrossmintProvider,
_17
CrossmintAuthProvider,
_17
CrossmintWalletProvider
_17
} from "@crossmint/client-sdk-react-ui";
_17
_17
export function Providers({ children }: { children: React.ReactNode }) {
_17
return (
_17
<CrossmintProvider apiKey="<crossmint-client-api-key>">
_17
<CrossmintAuthProvider>
_17
{children}
_17
</CrossmintAuthProvider>
_17
</CrossmintProvider>
_17
);
_17
}

Step 3: Create Authentication Component​


_39
"use client";
_39
_39
import { useAuth } from "@crossmint/client-sdk-react-ui";
_39
_39
export function AuthButton() {
_39
const { login, logout, user, jwt } = useAuth();
_39
_39
return (
_39
<div className="flex gap-4">
_39
{user == null ? (
_39
<button
_39
type="button"
_39
onClick={login}
_39
className="bg-blue-500 text-white font-bold py-2 px-4 rounded"
_39
>
_39
Login
_39
</button>
_39
) : (
_39
<button
_39
type="button"
_39
onClick={logout}
_39
className="bg-black text-white font-bold py-2 px-4 rounded border-2 border-blue-500"
_39
>
_39
Logout
_39
</button>
_39
)}
_39
_39
{/* Display user information */}
_39
<div className="user-info">
_39
<p>User ID: {user?.userId}</p>
_39
<p>Email: {user?.email ?? "None"}</p>
_39
<p>Phone: {user?.phoneNumber ?? "None"}</p>
_39
<p>Farcaster: {user?.farcaster?.username ?? "None"}</p>
_39
<p>Google: {user?.google?.displayName ?? "None"}</p>
_39
<p>JWT: {jwt}</p>
_39
</div>
_39
</div>
_39
);
_39
}

Environment Configuration​


_10
// Use environment-specific API keys
_10
const crossmintConfig = {
_10
apiKey: process.env.NODE_ENV === 'production'
_10
? process.env.CROSSMINT_PROD_API_KEY
_10
: process.env.CROSSMINT_STAGING_API_KEY,
_10
environment: process.env.NODE_ENV === 'production' ? 'production' : 'staging'
_10
};

Production Deployment​

1. Create Production Account​

  1. Create a developer account on the Production Console Production Console Login

  2. Complete account verification and KYB process

2. Configure Production API Keys​

  1. Create a production client API key

Navigate to Integrate > API Keys

API Keys

  1. Enable required scopes:
    • users.create
    • users.read
    • wallets.read
    • wallets.create

3. Update Environment Variables​


_10
# Production
_10
CROSSMINT_API_KEY=your_production_client_api_key
_10
CROSSMINT_ENVIRONMENT=production
_10
_10
# Staging (for testing)
_10
CROSSMINT_API_KEY=your_staging_client_api_key
_10
CROSSMINT_ENVIRONMENT=staging

4. Test Authentication Flow​


_12
// Test authentication in staging first
_12
const testAuth = async () => {
_12
const { login, user } = useAuth();
_12
_12
await login();
_12
_12
if (user) {
_12
console.log('Authentication successful:', user);
_12
// Test wallet creation
_12
await createUserWallet();
_12
}
_12
};

🔧 Troubleshooting​

Common Issues​

Authentication fails:

  • Verify API key is correct
  • Check authentication scopes are enabled
  • Ensure you're using the right environment (staging vs production)

Wallet creation fails:

  • Verify user is authenticated
  • Check wallet creation scopes
  • Ensure proper wallet configuration for Flow

Getting Help​

Rate this page