@emblemvault/emblem-auth-react

React hooks and components for Emblem wallet authentication.

Installation

npm install @emblemvault/emblem-auth-react

Why Use Emblem Auth React?

This library provides a secure, user-friendly authentication experience for Emblem Vault applications:

• Better Security: User-controlled wallet authentication instead of embedded API keys
• Better UX: Modal-based wallet connection flow with session management
• Auto Token Refresh: Handles JWT lifecycle automatically
• Ready-to-use Components: Pre-built UI components like ConnectButton and AuthStatus

Migrating from API keys? This library replaces the deprecated apiKey prop pattern used in other Emblem packages. Users connect their own wallets instead of using a shared API key.

Quick Start

import {
  EmblemAuthProvider,
  ConnectButton,
  useEmblemAuth,
} from '@emblemvault/emblem-auth-react';

function App() {
  return (
    <EmblemAuthProvider appId="your-app-id">
      <Header />
      <Content />
    </EmblemAuthProvider>
  );
}

function Header() {
  return <ConnectButton showVaultInfo />;
}

function Content() {
  const { isAuthenticated, walletAddress, vaultId } = useEmblemAuth();

  if (!isAuthenticated) {
    return <p>Please connect to continue</p>;
  }

  return (
    <div>
      <p>Wallet: {walletAddress}</p>
      <p>Vault: {vaultId}</p>
    </div>
  );
}

API Reference

EmblemAuthProvider

Wrap your app to provide authentication context.

<EmblemAuthProvider
  appId="your-app-id"
  authUrl="https://auth.emblemvault.ai"  // optional - auth service for modal, init, bootstrap, refresh
  apiUrl="https://api.emblemvault.ai"    // optional - backend API for vault operations
>
  {children}
</EmblemAuthProvider>

Props:

• appId (required) - Your registered application ID
• authUrl (optional) - Auth service URL for authentication flow. Defaults to https://auth.emblemvault.ai
• apiUrl (optional) - Backend API URL for vault operations. Defaults to https://api.emblemvault.ai
• debug (optional) - Enable debug logging

useEmblemAuth

Access auth state and actions.

const {
  // State
  isAuthenticated,  // boolean
  isLoading,        // boolean
  error,            // Error | null
  session,          // AuthSession | null
  walletAddress,    // string | null
  vaultId,          // string | null
  authSDK,          // EmblemAuthSDK instance

  // Actions
  openAuthModal,    // () => Promise<void>
  logout,           // () => void
  refreshSession,   // () => Promise<void>
} = useEmblemAuth();

useEmblemAuthOptional

Same as useEmblemAuth but returns null when used outside EmblemAuthProvider instead of throwing an error.

When to use:

• Components that may render with or without auth context
• Libraries/packages that support multiple authentication strategies (e.g., user login OR API key)
• Shared components used across apps with different auth setups

import { useEmblemAuthOptional } from '@emblemvault/emblem-auth-react';

function MyComponent() {
  const auth = useEmblemAuthOptional();

  // Gracefully handle missing provider
  if (!auth) {
    return <p>Auth provider not available</p>;
  }

  if (!auth.isAuthenticated) {
    return <button onClick={auth.openAuthModal}>Connect</button>;
  }

  return <p>Connected: {auth.walletAddress}</p>;
}

Comparison: | Hook | Outside Provider | |------|------------------| | useEmblemAuth() | Throws error | | useEmblemAuthOptional() | Returns null |

ConnectButton

Pre-styled connect/disconnect button.

<ConnectButton
  showVaultInfo    // Show vault dropdown when connected
  className=""     // Additional CSS classes
/>

AuthStatus

Display authentication status.

<AuthStatus
  showVaultInfo   // Show vault ID
  showLogout      // Show logout button
/>

Underlying SDK

This package wraps @emblemvault/auth-sdk for React. The SDK handles:

• JWT lifecycle and token refresh
• Wallet connection modal
• Session management

For advanced usage, access the SDK directly via useEmblemAuth().authSDK.

License

MIT