API Reference

Full SDK reference — all hooks, components, types, and server methods.

The complete API reference with every parameter, return type, and code example lives in the SDK README on npm. This page summarizes what's available and when to use each part.

React SDK (`@buildbase/sdk/react`)

Hooks

Hook	When to use
`useSaaSAuth()`	Sign in/out, get current user, check auth status, open settings
`useSessions()`	List and revoke the signed-in user's active sessions
`useDevices()`	List, rename, sign out, or forget the user's devices
`useConnectedAgents()`	List and disconnect AI agents connected to the user's account
`useMcpConnection()`	Read the MCP connection config for building a custom connect guide
`useSaaSWorkspaces()`	List, create, switch, update, delete workspaces
`useSubscription()`	Get current plan, status, billing interval
`useTrialStatus()`	Check trial state — `isTrialing`, `daysRemaining`, `isTrialEnding`
`useSeatStatus()`	Check seat limits — `memberCount`, `canInvite`, `inviteBlockReason`
`useCreditBalance()`	Get credit balance — `available`, `totalConsumed`, `totalGranted`
`useConsumeCredits()`	Deduct credits with idempotency
`usePurchaseCredits()`	Open Stripe checkout for credit packages
`useExpiringCredits()`	Get credits expiring within N days
`useQuotaUsageStatus()`	Get one quota's usage — `consumed`, `included`, `available`
`useAllQuotaUsage()`	Get all quotas at once
`useRecordUsage()`	Record usage against a quota
`usePermissions()`	Check permissions — `can()`, `isOwner`, `role`
`useTranslation()`	i18n — `t()`, `locale`, `dir`, `fmtCents()`, `fmtNum()`
`usePushNotifications()`	Subscribe/unsubscribe to browser push
`useUserAttributes()`	Get/update custom user attributes
`useUserFeatures()`	Check user-level feature flags
`usePublicPlans()`	Fetch plans without authentication (for public pricing pages)
`useCreateCheckoutSession()`	Create a Stripe Checkout session
`useInvoices()`	Paginated invoice history
`useInvoice()`	One invoice by id
`useBillingPortal()`	Get Stripe billing portal URL

Subscription management

Changing a subscription is separate from reading one. useSubscription() reads; these mutate.

Hook	When to use
`useSubscriptionManagement()`	Combined upgrade, downgrade, cancel and resume state
`useUpdateSubscription()`	Change plan or billing interval
`useCancelSubscription()`	Cancel immediately or at period end
`useResumeSubscription()`	Undo a scheduled cancellation

Plans, credits and usage data

Hook	When to use
`usePlanGroup()`	One plan group with its versions
`usePlanGroupVersions()`	Version history for a plan group
`usePublicPlanGroupVersion()`	A plan group version without authentication
`useCreditPackages()`	Purchasable credit packages
`usePublicCreditPackages()`	Credit packages without authentication
`useCreditTransactions()`	Paginated credit ledger
`useUsageLogs()`	Raw usage records behind a quota

The *Context hooks read state a provider already fetched, so they do not trigger a request of their own. The *Api hooks expose the imperative client behind the data hooks — reach for them only when the data hook does not fit.

Hook	Purpose
`useSaaSOs()`	The SDK instance and its configuration
`useSaaSSettings()`	Org settings resolved for the current app
`useUIConfig()`	Merged UI configuration
`useUIVisibility()`	Whether a given UI element should render
`useFullScreenLoader()`	Show or hide the SDK's full-screen loader
`useSubscriptionContext()`	Subscription state from `SubscriptionContextProvider`
`useCreditBalanceContext()`	Balance from `CreditBalanceContextProvider`
`useQuotaUsageContext()`	Quota state from `QuotaUsageContextProvider`
`useDevicesApi()`	Imperative devices client
`useSessionsApi()`	Imperative sessions client
`useConnectedAgentsApi()`	Imperative connected-agents client

40+ hooks total. See the full hook reference for parameters and return types.

Conditional components

Wrap UI in these — the SDK shows or hides children based on state. No if-statements needed.

Component	Shows children when...
`WhenAuthenticated` / `WhenUnauthenticated`	User is / isn't signed in
`WhenRoles` / `WhenWorkspaceRoles`	User has specific role(s)
`WhenPermission`	User has specific permission(s)
`WhenSubscription` / `WhenNoSubscription`	Workspace has / lacks a subscription
`WhenSubscriptionToPlans`	Subscribed to specific plan slug(s)
`WhenTrialing` / `WhenNotTrialing` / `WhenTrialEnding`	Trial state matches
`WhenQuotaAvailable` / `WhenQuotaExhausted` / `WhenQuotaOverage` / `WhenQuotaThreshold`	Quota usage matches condition
`WhenCreditsAvailable` / `WhenCreditsExhausted` / `WhenCreditsLow`	Credit balance matches condition
`WhenWorkspaceFeatureEnabled` / `WhenWorkspaceFeatureDisabled`	Workspace feature flag state
`WhenUserFeatureEnabled` / `WhenUserFeatureDisabled`	User feature flag state

20+ components total.

Pre-built pages and screens

Component	What it renders
`PricingPage`	Full pricing page with plan cards, interval toggle, Stripe checkout
`CreditStorePage`	Credit package store with pricing and purchase
`CreditBalance`	Current balance, ready to drop in a header or sidebar
`WorkspaceSwitcher`	Dropdown with search, create, and switch
`Devices` / `Sessions`	Device and session lists with sign-out controls
`ConnectedAgents`	AI agents connected to the account, with disconnect
`ConnectMcpGuide`	Generated instructions for connecting an agent over MCP
`BetaForm`	Beta signup/waitlist form
Workspace settings dialog	13 screens: profile, security, devices, connected-agents, general, users, subscription, usage, credits, features, notifications, permissions, danger

The settings dialog is not a standalone component — open it with openWorkspaceSettings(section), returned by useSaaSAuth(). Pass a SettingsScreen value (e.g. SettingsScreen.Devices) to open a specific screen.

Providers

SaaSOSProvider (also exported as BuildBaseProvider) is the only required one. The rest are opt-in: mount a context provider once high in the tree, then read it with the matching *Context hook instead of refetching per component.

Provider	Enables
`SaaSOSProvider`	Everything. Required at the app root
`SubscriptionContextProvider`	`useSubscriptionContext()`
`CreditBalanceContextProvider`	`useCreditBalanceContext()`
`CreditActionsProvider`	Credit consume and purchase actions
`QuotaUsageContextProvider`	`useQuotaUsageContext()`
`PushNotificationProvider`	`usePushNotifications()`

Layout helpers

Presentational components the SDK uses internally and re-exports so your own screens can match: EmptyState, LoadingState, FullScreenLoader, SectionHeader, StatusBanner, SidebarNavItem, SidebarNavSection.

Putting it together

SaaSOSProvider takes serverUrl, version, orgId and an auth block — see Installation for the full configuration. Once it is mounted, context providers nest inside it, and their hooks read that state without issuing a request of their own:

import {
  Permission,
  SubscriptionContextProvider,
  useSubscriptionContext,
  WhenPermission,
} from '@buildbase/sdk/react';

// Inside <SaaSOSProvider>, mount the context once...
function BillingArea({ children }: { children: React.ReactNode }) {
  return <SubscriptionContextProvider>{children}</SubscriptionContextProvider>;
}

// ...then read it anywhere below, with no extra fetch per component.
function PlanBadge() {
  const { subscription } = useSubscriptionContext();

  return (
    <WhenPermission permission={Permission.WORKSPACE_BILLING_VIEW}>
      <span>{subscription?.plan?.name ?? 'No plan'}</span>
    </WhenPermission>
  );
}

Server SDK (`@buildbase/sdk`)

See Server SDK for method signatures and examples. Key namespaces:

Namespace	What it does
`bb.subscription`	Get, checkout, update, cancel, resume subscriptions
`bb.credits`	Balance, consume, purchase, packages, transactions
`bb.usage`	Record usage, batch recording, quota status
`bb.workspace`	CRUD workspaces
`bb.users`	List, invite, remove, update roles, profile
`bb.notification`	Send email + push notifications
`bb.plans`	Get plan groups and versions
`bb.invoices`	List and get invoices
`bb.features`	List and toggle feature flags
`bb.permissions`	Check and resolve permissions for any user — both methods take an explicit `userId`

Data exports (`@buildbase/sdk/data`)

Reference data with no React dependency:

countries — country list with codes and flags
currencies — currency codes, symbols, and names
languages — language codes and names
timezones — IANA timezone list

MCP toolkit (`@buildbase/sdk/mcp`)

Server-side, framework-agnostic toolkit that turns your app into an MCP (Model Context Protocol) server, so AI agents can operate its BuildBase capabilities. Key exports: createMcpHandler() (stateless Streamable HTTP handler), defineMcpTool() / defineMcpResource() / defineMcpPrompt() (custom capabilities), builtinMcpTools and selectBuiltinTools() (ready-made BuildBase tools), buildbaseAuth() (Bearer-token verification for agent requests), and createAgentStack() (MCP server plus agent-discovery routes from one config).

Utilities (re-exported from core)

Category	Key exports
Billing math	`calculateTotalSubscriptionCents()`, `getBasePriceCents()`, `getPerSeatPriceCents()`, `getSeatPricing()`
Currency	`formatCents()`, `getCurrencySymbol()`, `getCurrencyFlag()`, `getPricingVariant()`
Permissions	`Permission.*` constants, `hasPermission()`, `resolvePermissions()`
Webhooks	`parseWebhookEvent()`, `verifyWebhookSignature()`
Auth intent	`saveAuthIntent()`, `consumeAuthIntent()` — preserve redirect across auth flow
Events	`eventEmitter` — SDK event bus for cross-component communication
Validation	`validateInvite()` — check seat limits before inviting

Full reference

For complete parameters, return types, TypeScript interfaces, and code examples for every export, see the SDK README on npm.