Authentication

Learn how to implement authentication with B3 Global Accounts

Tip

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:

Note

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

tsx
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

tsx
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:

tsx
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);
      }}
    />
  );
}
Note

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

typescript
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

typescript
// 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:

tsx
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>
  );
}
Note

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:

tsx
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:

tsx
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.

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.

Learn More
Examples

See complete integration examples.

Learn More
Try the Demo

Interactive authentication demo application.

Previous Global Accounts Introduction
Next Permissions & Session Keys
Ask a question... ⌘I