Server SDK

import Buildspace from "@buildspacestudio/sdk";

const bs = new Buildspace(process.env.BUILDSPACE_SECRET_KEY!);

Methods

`handleCallback(request, options)`

Exchanges an authorization code for a session token. Call this in your OAuth callback route.

const result = await bs.auth.handleCallback(request, { redirectUri });
// result: { access_token, expires_in, token_type, user }

`getSession(token)`

Validates a session token and returns the authenticated user. Sessions are managed by Better Auth on the server.

const session = await bs.auth.getSession(token);
// session: { appId, user: { id, email, name } }

`signOut(token?)`

Signs the user out. Pass a session token explicitly, or omit it if you've already attached one with bs.setSession(token).

await bs.auth.signOut(token);

bs.setSession(token);
await bs.auth.signOut();

signOut() clears the SDK's stored session state and treats already-expired or already-revoked sessions as safe no-ops, similar to Better Auth's sign-out flow.

`revokeSession(token)`

Invalidates a session token directly. This is the low-level primitive behind signOut().

await bs.auth.revokeSession(token);

Returns your app's Terms/Privacy URLs (set in Studio → Login branding → Terms & privacy) and whether this user has accepted the current Terms version. Users accept automatically when they sign in through the Buildspace login page; use this to re-prompt signed-in users after you publish a new version.

const terms = await bs.auth.getTermsStatus(token);
// { termsUrl, privacyUrl, termsVersion, acceptedVersion, acceptedAt, needsAcceptance }
if (terms.needsAcceptance) {
  redirect("/accept-terms");
}

`acceptTerms({ sessionToken, version })`

Records acceptance of the current Terms version, for example from your own "We've updated our Terms" screen. version must equal the current termsVersion (otherwise a 409 error), and repeated calls are no-ops.

await bs.auth.acceptTerms({ sessionToken: token, version: terms.termsVersion! });

Authentication infrastructure

The server SDK communicates with the Buildspace runtime API, which uses Better Auth for session storage, token management, and password hashing. All auth operations are handled server-side — no auth secrets are exposed to the client.

For details on the auth flow architecture, see the Overview.