Authentication

client.auth is Better Auth's React client. Its methods, return values, errors, session hook, fetch options, and session options follow Better Auth. Carpo configures the client base URL and Project Auth path for the selected project and environment.

function Account() {
  const { data: session, isPending, error } = carpo.auth.useSession()

  if (isPending) return <p>Checking your session...</p>
  if (error) return <p>Could not load the session.</p>
  return <p>{session?.user.name ?? 'Signed out'}</p>
}

const result = await carpo.auth.signIn.email({ email, password })
if (result.error) {
  console.error(result.error.message)
}

For a standalone Auth client without Database or Functions, import createCarpoAuthClient from @carpodev/carpo-sdk/auth.

import { createCarpoAuthClient } from '@carpodev/carpo-sdk/auth'

const auth = createCarpoAuthClient({
  apiUrl: 'https://api.carpo.dev',
  projectId: 'your-project-id',
  environment: 'development',
  sessionOptions: { refetchOnWindowFocus: true },
})

Configured client pluginsCopy Anchor Link

The client configures the Better Auth plugins used by Carpo Project Auth:

• Organizations and teams
• JWT
• Two factor authentication
• Username and admin
• API keys and passkeys
• Email OTP, magic link, and phone number
• Anonymous accounts
• Google One Tap when oneTapClientId is provided
• SIWE and last login method

Project Auth settings determine which sign in methods are enabled on the server. Passing an additional Better Auth client plugin only adds its client methods. The matching server plugin and configuration must also be enabled.

The factory accepts Better Auth's fetchOptions, sessionOptions, and disableDefaultFetchPlugins options. See Better Auth's reference for method specific parameters and plugin behavior.

Bearer authenticationCopy Anchor Link

Cookies are sent by default. For a flow based on a Project Auth JWT or a user scoped Project Auth API key, provide a rotating token getter:

carpo.database.setAccessTokenProvider(async () => {
  const { data, error } = await carpo.auth.token()
  if (error) return null
  return data?.token ?? null
}, { cacheKey: currentUserId })

You can pass getAccessToken and getAccessTokenCacheKey in createCarpoClient when the token source already exists at client initialization:

const carpo = createCarpoClient({
  apiUrl: 'https://api.carpo.dev',
  projectId: 'your-project-id',
  databaseId: 'your-database-id',
  getAccessToken: getCurrentUserToken,
  getAccessTokenCacheKey: () => currentUserId,
})

When using bearer credentials without an active Better Auth session, provide a stable, non secret user identity as the cache key. Do not use the bearer token itself as a query key. When you set a provider after client creation, pass the identity with setAccessTokenProvider(getToken, { cacheKey: userId }). The same token store is shared with Storage when Storage is configured.