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
`useBillingPortal()`	Get Stripe billing portal URL

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

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

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
`WorkspaceSwitcher`	Dropdown with search, create, and switch
`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.

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.