BuildBaseBuildBase

Quickstart

Go from zero to a working app with auth, workspaces, and billing in 5 minutes.

Step 1: Install

npm install @buildbase/sdk

Step 2: Create the provider

import { ApiVersion } from '@buildbase/sdk';
import { SaaSOSProvider } from '@buildbase/sdk/react';

import '@buildbase/sdk/css';

function BuildBaseProvider({ children }: { children: React.ReactNode }) {
  return (
    <SaaSOSProvider
      serverUrl="https://api.console.buildbase.app"
      version={ApiVersion.V1}
      orgId="your-org-id"
      auth={{
        clientId: 'your-client-id',
        redirectUrl: 'http://localhost:3000/callback',
        callbacks: {
          getSession: async () => {
            const res = await fetch('/api/auth/session');
            const data = await res.json();
            return data.sessionId ?? null;
          },
          handleAuthentication: async (code) => {
            const res = await fetch('/api/auth/verify', {
              method: 'POST',
              body: JSON.stringify({ code }),
            });
            const data = await res.json();
            return { sessionId: data.sessionId };
          },
          onSignOut: async () => {
            await fetch('/api/auth/signout', { method: 'POST' });
          },
        },
      }}
    >
      {children}
    </SaaSOSProvider>
  );
}

export default BuildBaseProvider;

Step 3: Add sign-in

import {
  useSaaSAuth,
  WhenAuthenticated,
  WhenUnauthenticated,
} from '@buildbase/sdk/react';

function Dashboard() {
  const { user, signIn, signOut } = useSaaSAuth();

  return (
    <>
      <WhenUnauthenticated>
        <button onClick={signIn}>Sign In</button>
      </WhenUnauthenticated>

      <WhenAuthenticated>
        <p>Welcome, {user?.name}</p>
        <button onClick={signOut}>Sign Out</button>
      </WhenAuthenticated>
    </>
  );
}

Step 4: Add a workspace switcher

import { WorkspaceSwitcher } from '@buildbase/sdk/react';

function TeamPage() {
  return (
    <div>
      <WorkspaceSwitcher
        trigger={(isLoading, ws) => (
          <button>{ws?.name ?? 'Select workspace'}</button>
        )}
      />
      <h1>Workspace Dashboard</h1>
    </div>
  );
}

Step 5: Open settings

import { useSaaSAuth } from '@buildbase/sdk/react';

function BillingPage() {
  const { openWorkspaceSettings } = useSaaSAuth();

  return (
    <button onClick={() => openWorkspaceSettings('subscription')}>
      Manage Subscription
    </button>
  );
}

What happened

  1. SaaSOSProvider connects your app to BuildBase and sets up auth, workspace context, and permissions.
  2. useSaaSAuth() gives you the current user, sign-in, and sign-out functions. BuildBase handles the full OAuth flow.
  3. WhenAuthenticated and WhenUnauthenticated conditionally render UI based on auth state — no manual checks.
  4. WorkspaceSwitcher renders a drop-in component for switching between workspaces.
  5. openWorkspaceSettings('subscription') (from useSaaSAuth()) opens the pre-built billing management UI.

Next Steps

  • Going to Production — Env vars, API routes, project structure, and deployment checklist.
  • Authentication — Sign-in, social login, session management.
  • Workspaces — Create workspaces, manage members, handle invites.
  • Billing — Subscription plans, checkout, usage tracking.
  • Permissions — Role-based access control and conditional rendering.