Banata

Configure Authentication

Email & Password

Set up email and password authentication with email verification, password reset, and customizable validation.

Email and password is the most common authentication method. Banata Auth provides a complete implementation with email verification, password reset, configurable validation rules, and automatic audit logging.

Enabling Email & Password

From the Dashboard

  1. Go to Authentication > Methods in your project.
  2. Toggle on Email & Password.
  3. Configure an email provider under Emails > Providers (required for verification and password reset emails).
  4. Customize email templates under Email Templates if needed.

From the SDK

ts
await banata.configuration.saveDashboardConfig({
  authMethods: {
    emailPassword: true,
  },
  emailPassword: {
    requireEmailVerification: true,
    autoSignIn: true,
    minPasswordLength: 8,
    maxPasswordLength: 128,
  },
});

Configuration Options

OptionDefaultDescription
requireEmailVerificationtrueUsers must verify their email before signing in
autoSignIntrueAutomatically create a session after sign-up
minPasswordLength8Minimum password length
maxPasswordLength128Maximum password length

Sign Up

Use the auth client to create a new account:

ts
import { authClient } from "@/lib/auth-client";
 
const { data, error } = await authClient.signUp.email({
  email: "jane@example.com",
  password: "securePassword123",
  name: "Jane Doe",
});
 
if (error) {
  console.error(error.message);
  // Possible errors:
  // - "User already exists" (409)
  // - "Invalid email" (422)
  // - "Password too short" (422)
} else {
  console.log(data.user);    // { id, email, name, ... }
  console.log(data.session); // { id, token, expiresAt, ... }
}

If email verification is enabled, the user receives a verification email after signing up. If autoSignIn is enabled, they also get a session immediately (but some features may be restricted until verification).

Using the Pre-Built Form

tsx
import { SignUpForm } from "@banata-auth/react";
import { authClient } from "@/lib/auth-client";
 
export default function SignUpPage() {
  return (
    <SignUpForm
      authClient={authClient}
      callbackURL="/dashboard"
      onError={(error) => console.error(error.message)}
    />
  );
}

Sign In

ts
const { data, error } = await authClient.signIn.email({
  email: "jane@example.com",
  password: "securePassword123",
});
 
if (error) {
  console.error(error.message);
  // Possible errors:
  // - "Invalid email or password" (401)
  // - "Email not verified" (403)
  // - "Account is banned" (403)
  // - "Too many attempts" (429)
} else {
  window.location.href = "/dashboard";
}

Using the Pre-Built Form

tsx
import { SignInForm } from "@banata-auth/react";
import { authClient } from "@/lib/auth-client";
 
export default function SignInPage() {
  return (
    <SignInForm
      authClient={authClient}
      callbackURL="/dashboard"
      onError={(error) => console.error(error.message)}
    />
  );
}

Sign Out

ts
await authClient.signOut();
window.location.href = "/sign-in";

Password Reset

Step 1: Request a Reset Link

The user enters their email address and Banata sends a password reset email:

ts
const { error } = await authClient.forgetPassword({
  email: "jane@example.com",
  redirectTo: "/reset-password",
});
 
if (!error) {
  // Show "Check your email" message
}

Step 2: Reset the Password

On the /reset-password page, extract the token from the URL and submit the new password:

ts
const token = new URLSearchParams(window.location.search).get("token");
 
const { error } = await authClient.resetPassword({
  newPassword: "newSecurePassword456",
  token: token!,
});
 
if (!error) {
  window.location.href = "/sign-in";
}

Email Verification

Email verification happens automatically when the user clicks the link in the verification email. The link hits /api/auth/verify-email with the token, and Banata handles the rest.

To resend the verification email:

ts
await authClient.sendVerificationEmail({
  email: "jane@example.com",
  callbackURL: "/dashboard",
});

Server-Side User Management

Use the admin SDK to manage users from your backend:

ts
import { BanataAuth } from "@banata-auth/sdk";
 
const banata = new BanataAuth({
  apiKey: process.env.BANATA_API_KEY!,
  baseUrl: "https://auth.banata.dev",
});
 
// List users
const { data, listMetadata } = await banata.userManagement.listUsers({ limit: 20 });
 
// Create a user programmatically
await banata.userManagement.createUser({
  email: "admin@example.com",
  password: "securePassword123",
  name: "Admin User",
  role: "admin",
});
 
// Update a user
await banata.userManagement.updateUser({
  userId: "usr_01...",
  name: "Updated Name",
  metadata: { plan: "pro" },
});
 
// Ban a user
await banata.userManagement.banUser({ userId: "usr_01..." });
 
// Delete a user
await banata.userManagement.deleteUser({ userId: "usr_01..." });

Password Validation

Passwords are validated on both sign-up and password reset:

RuleDefault
Minimum length8 characters
Maximum length128 characters

If a password doesn't meet the requirements, a ValidationError (422) is returned. You can add custom client-side validation in your forms for additional rules (uppercase, numbers, special characters) before calling the API.

Rate Limits

EndpointLimit
Sign in30 requests per minute
Sign up10 requests per minute

Rate limits are project-scoped and identifier-aware for email-based endpoints.

Error Reference

ErrorStatusCause
AuthenticationError401Invalid email or password
ForbiddenError403Email not verified, or account banned
ConflictError409Email already registered
ValidationError422Invalid email format or password too short/long
RateLimitError429Too many sign-in or sign-up attempts

Security Best Practices

  1. Enable email verification — prevents sign-up with someone else's email address.
  2. Use HTTPS in production — session cookies are Secure-flagged.
  3. Set a strong BETTER_AUTH_SECRET — use openssl rand -base64 32 to generate one.
  4. Don't disable rate limiting — the defaults prevent brute force attacks.

Next Steps