Client SDK (React)¶

React components and hooks for AuthVital authentication.

The AuthVital Client SDK provides React components and hooks for managing authentication state in your frontend application.

Overview¶

The SDK handles:

• 🔐 Authentication state management - Track user login status
• 👤 User data access - Display user info, roles, permissions
• 🏢 Multi-tenant support - Tenant selection and switching
• 📨 Invitation flows - Accept and process team invitations
• 🚀 OAuth initiation - Start login/signup flows that redirect to AuthVital

⚠️ Important: Cookie-Based Authentication¶

The Client SDK does NOT call the AuthVital IDP directly!

Auth state is managed via httpOnly cookies that your server sets. This is intentional for XSS protection:

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Browser   │         │ Your Server │         │  AuthVital  │
│  (Client)   │         │   (API)     │         │    IDP      │
└──────┬──────┘         └──────┬──────┘         └──────┬──────┘
       │                       │                       │
       │  1. Redirect to OAuth │                       │
       │──────────────────────────────────────────────>│
       │                       │                       │
       │  2. OAuth callback with code                  │
       │<──────────────────────────────────────────────│
       │                       │                       │
       │  3. POST code to your server                  │
       │──────────────────────>│                       │
       │                       │  4. Exchange code     │
       │                       │──────────────────────>│
       │                       │  5. Return JWT        │
       │                       │<──────────────────────│
       │                       │                       │
       │  6. Set httpOnly cookie + return user data    │
       │<──────────────────────│                       │
       │                       │                       │
       │  7. setAuthState(user, tenants)               │
       │  (Client updates React state)                 │
       └───────────────────────────────────────────────┘

Key Points:

• ✅ Tokens are stored in httpOnly cookies (set by YOUR server)
• ✅ JavaScript cannot access the actual JWT tokens
• ✅ Your server verifies JWTs using getCurrentUser() from the Server SDK
• ✅ Server passes user data to client via props or API response
• ✅ Client updates state via setAuthState(user, tenants)
• ❌ No getAccessToken() method - tokens aren't accessible from JS!

Installation¶

npm install @authvital/sdk

Quick Setup¶

import { AuthVitalProvider, useAuth } from '@authvital/sdk/client';

function App() {
  // initialUser/initialTenants come from your server (SSR props, API call, etc.)
  const { initialUser, initialTenants } = useServerData();

  return (
    <AuthVitalProvider
      authVitalHost={import.meta.env.VITE_AUTHVITAL_HOST}
      clientId={import.meta.env.VITE_AUTHVITAL_CLIENT_ID}
      initialUser={initialUser}
      initialTenants={initialTenants}
    >
      <MyApp />
    </AuthVitalProvider>
  );
}

function MyApp() {
  const { user, isAuthenticated, logout } = useAuth();

  if (!isAuthenticated) {
    return <LoginPage />;
  }

  return (
    <div>
      <p>Welcome, {user?.email}!</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

AuthVitalProvider¶

Wrap your app with AuthVitalProvider to enable authentication:

import { AuthVitalProvider } from '@authvital/sdk/client';

function App() {
  return (
    <AuthVitalProvider
      authVitalHost="https://auth.yourapp.com"
      clientId="your-client-id"
      redirectUri="https://yourapp.com/api/auth/callback"  // Optional
      initialUser={null}                                   // From server
      initialTenants={[]}                                  // From server
      onAuthStateChange={(user) => {                       // Optional callback
        console.log('Auth state changed:', user);
      }}
    >
      <Router>
        <Routes />
      </Router>
    </AuthVitalProvider>
  );
}

Provider Props¶

Environment Variables¶

# .env (Vite)
VITE_AUTHVITAL_HOST=https://auth.yourapp.com
VITE_AUTHVITAL_CLIENT_ID=your-client-id

# .env (Create React App)
REACT_APP_AUTHVITAL_HOST=https://auth.yourapp.com
REACT_APP_AUTHVITAL_CLIENT_ID=your-client-id

# .env (Next.js - client-side)
NEXT_PUBLIC_AUTHVITAL_HOST=https://auth.yourapp.com
NEXT_PUBLIC_AUTHVITAL_CLIENT_ID=your-client-id

Documentation Structure¶

Next Steps¶

1. Hooks Reference - Learn about useAuth and other hooks
2. Components - Explore pre-built components
3. Patterns - Common implementation patterns
4. Server SDK - Server-side token verification