Email & Password

Pulsabase Auth provides native support for email and password authentication, complete with secure bcrypt password hashing, automatic token management, MFA, password resets, and email verification.

Auth Lifecycle

Sign Up

Register a new user. On success, the session tokens are automatically stored and the user is immediately signed in.

If your project requires email verification, a confirmation email is automatically sent.

TypeScript

import pb from './pulsabase';

const { user_id, access_token } = await pb.auth.signUpWithPassword(
  'user@example.com',
  'StrongPassword123!',
  {
    given_name: 'John',
    family_name: 'Doe',
    // Optional: store arbitrary metadata
    user_metadata: { plan: 'free', referral: 'homepage' },
  }
);

Dart

import 'client.dart';

final result = await pb.auth.signUpWithPassword(
  'user@example.com',
  'StrongPassword123!',
  givenName: 'John',
  familyName: 'Doe',
);

print(result.userId);

Sign In

Authenticate an existing user. On success, the SDK automatically stores the session tokens and schedules silent refreshes.

TypeScript

const session = await pb.auth.signInWithPassword(
  'user@example.com',
  'StrongPassword123!'
);

// Handle MFA if enabled for this account
if ('mfa_required' in session) {
  const mfaCode = await promptUserForCode();
  await pb.auth.signInWithPassword(
    'user@example.com',
    'StrongPassword123!',
    mfaCode   // 6-digit TOTP code
  );
}

Dart

try {
  final tokens = await pb.auth.signInWithPassword(
    'user@example.com',
    'StrongPassword123!',
  );
} on PulsabaseApiException catch (e) {
  if (e.code == 'MFA_REQUIRED') {
    final code = await promptUserForCode();
    await pb.auth.signInWithPassword(
      'user@example.com',
      'StrongPassword123!',
      mfaCode: code,
    );
  }
}

Sign Out

Sign the user out and clear the local session. All SDK requests will become unauthenticated after this call.

TypeScript

await pb.auth.signOut();

Dart

await pb.auth.signOut();

Password Resets

A two-step flow for users who have forgotten their password.

Step 1 — Request Reset

Sends an email to the user with a reset link. You configure the link’s destination URL in Dashboard → Settings → Email Templates.

TypeScript

await pb.auth.resetPassword('user@example.com');
// No error is thrown even if the email doesn't exist (security best practice)

Dart

await pb.auth.resetPassword('user@example.com');

Step 2 — Confirm Reset

When the user clicks the link in their email, extract the token from the URL parameters and call confirmResetPassword.

TypeScript

// On your /reset-password route: ?token=XYZ
const urlParams = new URLSearchParams(window.location.search);
const token = urlParams.get('token');

await pb.auth.confirmResetPassword(token, 'NewStrongPassword123!');

Dart

// token retrieved from deep link / URL
await pb.auth.confirmResetPassword(
  'token_from_url',
  'NewStrongPassword123!',
);

Updating Password (Authenticated)

If a user is already signed in and wants to change their password, they must provide their current password for security verification.

TypeScript

await pb.auth.updatePassword('CurrentPassword123!', 'NewPassword456!');

Dart

await pb.auth.updatePassword('CurrentPassword123!', 'NewPassword456!');

Email Verification

If your project requires email verification, users receive a verification email upon registration. You can also re-request the verification email.

Request Verification Email

// Requires the user to be signed in
await pb.auth.requestEmailVerification();

Confirm Email Verification

// token comes from the link in the verification email
await pb.auth.confirmEmailVerification('token_from_email');

Multi-Factor Authentication (MFA)

Pulsabase supports TOTP-based MFA (compatible with Google Authenticator, Authy, etc.).

Enroll

const { qr_code_url, recovery_codes } = await pb.auth.mfa.enroll();

// Display qr_code_url to the user for scanning
// Store recovery_codes securely — shown only once!

Verify (Activate MFA)

await pb.auth.mfa.verify('123456'); // 6-digit code from the authenticator app

Disable MFA

await pb.auth.mfa.disable();