Authentication

Learn how to implement authentication with B3 Global Accounts

For Developers: All demos are hosted in the global-accounts app. To test locally, run pnpm dev in the global-accounts directory and access demos at http://localhost:5173/demos.

Interactive Demo

Experience B3 authentication in action with all available providers:

This is a live, interactive demo using the actual B3 SDK. When you don’t specify strategies, all available authentication options are displayed. View the full demo page for more examples.

Authentication Strategies

B3 Global Accounts support multiple authentication strategies to fit your application’s needs.

Social Login

Google Authentication

import { SignInWithB3 } from "@b3dotfun/sdk/global-account/react";

const b3Chain = {
  id: 8333,
  name: "B3",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpc: "https://mainnet-rpc.b3.fun",
};

function GoogleAuth() {
  return (
    <SignInWithB3
      strategies={["google"]}
      chain={b3Chain}
      partnerId="your-partner-id"
      onLoginSuccess={(globalAccount) => {
        console.log("Google auth successful:", globalAccount);
      }}
      onError={async (error) => {
        console.error("Authentication failed:", error);
      }}
    />
  );
}

Discord Authentication

import { SignInWithB3 } from "@b3dotfun/sdk/global-account/react";

const b3Chain = {
  id: 8333,
  name: "B3",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpc: "https://mainnet-rpc.b3.fun",
};

function DiscordAuth() {
  return (
    <SignInWithB3
      strategies={["discord"]}
      chain={b3Chain}
      partnerId="your-partner-id"
      onLoginSuccess={(globalAccount) => {
        console.log("Discord auth successful:", globalAccount);
      }}
      onError={async (error) => {
        console.error("Authentication failed:", error);
      }}
    />
  );
}

Multiple Specific Strategies

You can allow users to choose from multiple specific authentication providers:

import { SignInWithB3 } from "@b3dotfun/sdk/global-account/react";

const b3Chain = {
  id: 8333,
  name: "B3",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpc: "https://mainnet-rpc.b3.fun",
};

function MultipleAuthOptions() {
  return (
    <SignInWithB3
      strategies={["google", "discord", "x"]}
      chain={b3Chain}
      partnerId="your-partner-id"
      onLoginSuccess={(globalAccount) => {
        console.log("Auth successful:", globalAccount);
      }}
    />
  );
}

Specify an array of strategies to show only those authentication options to your users.

Headless Authentication

For custom implementations, use the headless authentication service:

Basic Authentication

import { authenticate } from "@b3dotfun/sdk/global-account/app";

async function authenticateUser(accessToken: string, identityToken: string) {
  try {
    const authResult = await authenticate(accessToken, identityToken, {
      // additional configuration
    });
    
    if (authResult) {
      console.log("Authentication successful:", authResult);
      return authResult;
    } else {
      console.log("Authentication failed");
      return null;
    }
  } catch (error) {
    console.error("Authentication error:", error);
    throw error;
  }
}

React Native Authentication

// For React Native applications
import { authenticate } from "@b3dotfun/sdk/global-account/app";

async function authenticateInReactNative() {
  const result = await authenticate("access-token", "identity-token");
  return result;
}

Authentication Hooks

useB3 Hook

The primary hook for accessing authentication state:

import { useB3 } from "@b3dotfun/sdk/global-account/react";

function AuthStatus() {
  const { account, user } = useB3();

  return (
    <div>
      {account ? (
        <div>
          <p>Welcome, {user?.displayName}!</p>
          <p>Account Address: {account.address}</p>
        </div>
      ) : (
        <p>Please sign in</p>
      )}
    </div>
  );
}

The useB3 hook provides access to the authenticated account (wallet account) and user (user profile data). Use useAuthStore to access loading and authentication states.

useAccountWallet Hook

Access wallet information and connection status:

import { useAccountWallet } from "@b3dotfun/sdk/global-account/react";

function WalletInfo() {
  const { wallet, address, ensName } = useAccountWallet();

  return (
    <div>
      {address && (
        <div>
          <p>Wallet Address: {address}</p>
          {ensName && <p>ENS: {ensName}</p>}
          {wallet?.meta?.icon && <img src={wallet.meta.icon} alt="Wallet icon" />}
        </div>
      )}
    </div>
  );
}

Error Handling

Implement proper error handling for authentication flows:

function AuthWithErrorHandling() {
  const [authError, setAuthError] = useState<string | null>(null);

  return (
    <div>
      <SignInWithB3
        strategies={["google", "discord"]}
        chain={b3Chain}
        partnerId="your-partner-id"
        onLoginSuccess={(globalAccount) => {
          setAuthError(null);
          console.log("Success:", globalAccount);
        }}
        onError={async (error) => {
          setAuthError(error.message);
          console.error("Auth error:", error);
        }}
      />
      
      {authError && (
        <div className="error">
          Authentication failed: {authError}
        </div>
      )}
    </div>
  );
}

Best Practices

Partner ID

Always use your unique partner ID for proper attribution and analytics.

Error Handling

Implement comprehensive error handling for better user experience.

Session Management

Set appropriate session durations based on your application’s security needs.

Environment Config

Use proper environment variables for different deployment stages.

Component API Reference

SignInWithB3

The main authentication button component.

Props

strategies · AllowedStrategy[]

Array of authentication strategies to display. Options include: "google", "github", "email", "discord", "x", "apple", "walletConnect", "io.metamask", "com.coinbase.wallet".

Leave undefined to show all options.

chain · Chain · required

Blockchain chain configuration object with id, name, nativeCurrency, and rpc.

partnerId · string · required

Your unique partner ID for B3 Global Accounts.

onLoginSuccess · (account: Account) => void

Callback function called when authentication succeeds.

onError · (error: Error) => Promise<void>

Async callback function called when an error occurs.

closeAfterLogin · boolean · default: "false"

Whether to close the modal after successful login.

buttonText · string | ReactNode

Custom text or component for the sign-in button.

withLogo · boolean · default: "true"

Whether to show the B3 logo in the button.

Available Authentication Strategies

B3 Global Accounts supports the following authentication methods:

Strategy	Type	Description
"google"	Social	Google OAuth authentication
"discord"	Social	Discord OAuth authentication
"github"	Social	GitHub OAuth authentication
"x"	Social	X (formerly Twitter) authentication
"apple"	Social	Apple Sign In
"guest"	Passwordless	Guest authentication without signup
"email"	Passwordless	Email verification code authentication
"walletConnect"	Wallet	WalletConnect protocol
"io.metamask"	Wallet	MetaMask browser extension
"com.coinbase.wallet"	Wallet	Coinbase Wallet

Next Steps

Hooks Reference

Explore all available React hooks.

Examples

See complete integration examples.

Try the Demo

Interactive authentication demo application.