> ## Documentation Index
> Fetch the complete documentation index at: https://docs.b3.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to implement authentication with B3 Global Accounts

<Tip>
  **For Developers**: All demos are hosted in the [global-accounts app](https://github.com/b3-fun/b3/tree/main/apps/global-accounts). To test locally, run `pnpm dev` in the global-accounts directory and access demos at `http://localhost:5173/demos`.
</Tip>

## Interactive Demo

Experience B3 authentication in action with all available providers:

<iframe
  src="https://global.b3.fun/demos?embedded=true#auth-all"
  style={{
width: '100%',
height: '500px',
border: '1px solid #e5e7eb',
borderRadius: '8px',
marginTop: '16px',
marginBottom: '16px',
overscrollBehavior: 'contain' 
}}
  title="B3 Authentication Demo"
/>

<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](https://global.b3.fun/demos) for more examples.
</Note>

## Authentication Strategies

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

## Social Login

### Google Authentication

<iframe
  src="https://global.b3.fun/demos?embedded=true#auth-google"
  style={{
width: '100%',
height: '300px',
border: '1px solid #e5e7eb',
borderRadius: '8px',
marginTop: '16px',
marginBottom: '16px',
overscrollBehavior: 'contain' 
}}
  title="Google Authentication Demo"
/>

```tsx theme={null}
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 theme={null}
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:

<iframe
  src="https://global.b3.fun/demos?embedded=true#auth-full"
  style={{
width: '100%',
height: '300px',
border: '1px solid #e5e7eb',
borderRadius: '8px',
marginTop: '16px',
marginBottom: '16px',
overscrollBehavior: 'contain' 
}}
  title="Multiple Authentication Strategies Demo"
/>

```tsx theme={null}
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.
</Note>

## Headless Authentication

For custom implementations, use the headless authentication service:

### Basic Authentication

```typescript theme={null}
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 theme={null}
// 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 theme={null}
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.
</Note>

### useAccountWallet Hook

Access wallet information and connection status:

```tsx theme={null}
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 theme={null}
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

<CardGroup cols={2}>
  <Card title="Partner ID" icon="id-badge">
    Always use your unique partner ID for proper attribution and analytics.
  </Card>

  <Card title="Error Handling" icon="exclamation-triangle">
    Implement comprehensive error handling for better user experience.
  </Card>

  <Card title="Session Management" icon="clock">
    Set appropriate session durations based on your application's security needs.
  </Card>

  <Card title="Environment Config" icon="settings">
    Use proper environment variables for different deployment stages.
  </Card>
</CardGroup>

## Component API Reference

### SignInWithB3

The main authentication button component.

#### Props

<ParamField path="strategies" type="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.
</ParamField>

<ParamField path="chain" type="Chain" required>
  Blockchain chain configuration object with `id`, `name`, `nativeCurrency`, and `rpc`.
</ParamField>

<ParamField path="partnerId" type="string" required>
  Your unique partner ID for B3 Global Accounts.
</ParamField>

<ParamField path="onLoginSuccess" type="(account: Account) => void">
  Callback function called when authentication succeeds.
</ParamField>

<ParamField path="onError" type="(error: Error) => Promise<void>">
  Async callback function called when an error occurs.
</ParamField>

<ParamField path="closeAfterLogin" type="boolean" default="false">
  Whether to close the modal after successful login.
</ParamField>

<ParamField path="buttonText" type="string | ReactNode">
  Custom text or component for the sign-in button.
</ParamField>

<ParamField path="withLogo" type="boolean" default="true">
  Whether to show the B3 logo in the button.
</ParamField>

## Available Authentication Strategies

B3 Global Accounts supports the following authentication methods:

<table>
  <thead>
    <tr>
      <th>Strategy</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`"google"`</td>
      <td>Social</td>
      <td>Google OAuth authentication</td>
    </tr>

    <tr>
      <td>`"discord"`</td>
      <td>Social</td>
      <td>Discord OAuth authentication</td>
    </tr>

    <tr>
      <td>`"github"`</td>
      <td>Social</td>
      <td>GitHub OAuth authentication</td>
    </tr>

    <tr>
      <td>`"x"`</td>
      <td>Social</td>
      <td>X (formerly Twitter) authentication</td>
    </tr>

    <tr>
      <td>`"apple"`</td>
      <td>Social</td>
      <td>Apple Sign In</td>
    </tr>

    <tr>
      <td>`"guest"`</td>
      <td>Passwordless</td>
      <td>Guest authentication without signup</td>
    </tr>

    <tr>
      <td>`"email"`</td>
      <td>Passwordless</td>
      <td>Email verification code authentication</td>
    </tr>

    <tr>
      <td>`"walletConnect"`</td>
      <td>Wallet</td>
      <td>WalletConnect protocol</td>
    </tr>

    <tr>
      <td>`"io.metamask"`</td>
      <td>Wallet</td>
      <td>MetaMask browser extension</td>
    </tr>

    <tr>
      <td>`"com.coinbase.wallet"`</td>
      <td>Wallet</td>
      <td>Coinbase Wallet</td>
    </tr>
  </tbody>
</table>

## Next Steps

<CardGroup cols={2}>
  <Card title="Hooks Reference" icon="react" href="/sdk/global-account/hooks">
    Explore all available React hooks.
  </Card>

  <Card title="Examples" icon="code" href="/sdk/global-account/examples">
    See complete integration examples.
  </Card>

  <Card title="Try the Demo" icon="play" href="https://login-minimal-b3.vercel.app/">
    Interactive authentication demo application.
  </Card>
</CardGroup>