Authentication

The SDK exposes auth flows under three namespaces:

• vb.auth.<collection> — per auth-collection user flows (login, register, OAuth, OTP, MFA, anonymous, totp)
• vb.auth.admin — admin-only flows (/api/v1/admin/auth/*)
• vb.auth.shared — flows that don’t depend on the collection (refresh, logout, /me)

The <collection> is whatever you named your auth collection (commonly users).

Email + password

// Register
await vb.auth.users.register({
  email: "alice@example.com",
  password: "long-password-here",
  // any extra fields defined on the collection
  name: "Alice",
});

// Login → token persisted in the auth store
const result = await vb.auth.users.login({
  email: "alice@example.com",
  password: "long-password-here",
});

if ("mfa_required" in result) {
  // MFA enabled — prompt for the 6-digit code
  await vb.auth.users.loginMfa({
    mfa_token: result.mfa_token,
    code: "123456",
  });
} else {
  console.log("Logged in as", result.record);
}

Email verification

await vb.auth.users.requestVerify();           // sends the email
await vb.auth.users.verifyEmail("token-from-link");

Password reset

await vb.auth.users.requestPasswordReset("alice@example.com");
await vb.auth.users.confirmPasswordReset("reset-token", "new-password");

OTP / magic-link

await vb.auth.users.otpRequest("alice@example.com");

// User pastes the 6-digit code (or clicks the magic link)
const result = await vb.auth.users.otpAuth({
  email: "alice@example.com",
  code: "123456",
});

Pairs with MFA: if the user has TOTP enabled, the result is MfaPending with a fresh mfa_token to complete via loginMfa.

TOTP (MFA)

// 1. Begin enrolment
const setup = await vb.auth.users.totpSetup();
// setup.secret  → show as QR
// setup.uri     → otpauth://… URI

// 2. User scans + enters a code from their authenticator
await vb.auth.users.totpConfirm({ code: "123456" });

// 3. Recovery codes
const codes = await vb.auth.users.totpRecoveryRegenerate();
//   → { codes: ["XXXX-XXXX", …, …] }   (10 fresh codes)

const status = await vb.auth.users.totpRecoveryStatus();
//   → { total: 10, used: 0, remaining: 10 }

// 4. Disable
await vb.auth.users.totpDisable({ code: "123456" });

During login with MFA enabled:

const result = await vb.auth.users.login({ email, password });
if ("mfa_required" in result) {
  // either a TOTP code or a recovery code:
  await vb.auth.users.loginMfa({ mfa_token: result.mfa_token, code: "123456" });
  // or:
  await vb.auth.users.loginMfa({ mfa_token: result.mfa_token, recovery_code: "XXXX-XXXX" });
}

OAuth2

Vaultbase ships out-of-the-box providers — Google, GitHub, GitLab, Facebook, Microsoft, Discord, Twitch, Spotify, LinkedIn, Slack, Bitbucket, Notion, Patreon, plus generic OIDC.

// 1. Discover what's enabled on your server
const providers = await vb.auth.users.listProviders();
//   → { providers: [{ name: "google", scopes: [...] }, …] }

// 2. Build authorize URL + redirect the browser
const { url, state, code_verifier } = await vb.auth.users.authorize({
  provider: "google",
  redirectUri: "https://app.example.com/oauth/callback",
});
// stash `state` + `code_verifier` (PKCE) in sessionStorage
window.location.assign(url);

// 3. On the callback page
const result = await vb.auth.users.exchange({
  provider: "google",
  code: new URLSearchParams(location.search).get("code")!,
  redirectUri: "https://app.example.com/oauth/callback",
  state: sessionStorage.getItem("state") ?? undefined,
  code_verifier: sessionStorage.getItem("code_verifier") ?? undefined,
});
//   → LoginResult — token persisted automatically

If the OAuth identity matches an existing email but isn’t yet linked, the exchange returns a merge_token instead. Confirm with:

await vb.auth.users.mergeConfirm({ merge_token, password: "current-pw" });

Unlink:

await vb.auth.users.unlinkOAuth("google");

Anonymous sessions

const guest = await vb.auth.users.anonymous();
// guest.token persisted; backed by an `is_anonymous: 1` user row

// Promote to a real account when ready (preserves user.id)
await vb.auth.users.promote({
  email: "alice@example.com",
  password: "long-password-here",
});

Refresh + logout

// Bumps the token's expiry against the same principal.
await vb.auth.shared.refresh();

// Server-side jti revocation + client-side store clear.
await vb.auth.shared.logout();

Admin flows

const me = await vb.auth.admin.me();        // null if not logged in
await vb.auth.admin.login({ email, password });
await vb.auth.admin.logout();

Auth state

The SDK persists the issued token in your configured AuthStore:

vb.client.authStore.get();    // → { token, record } | null
vb.client.authStore.set({ token: "manual-token", record: { id: "u1" } });
vb.client.authStore.clear();  // sign out without a server round-trip

Every authed request reads from the store, attaches Authorization: Bearer <token> (or rides the cookie via withCredentials), and falls back gracefully to skipAuth: true for endpoints that don’t need it (e.g. /login itself).