Auth Configuration - Banata Auth Docs

Banata Auth supports multiple authentication methods. You choose which ones to enable for each project, and configure their behavior through the dashboard or the SDK.

Available Auth Methods

Method	Description	Guide
Email & Password	Traditional sign-in with email verification and password reset	Email & Password
Social OAuth	Sign in with Google, GitHub, Apple, Microsoft, and 6 more providers	Social OAuth
Magic Links	Passwordless sign-in via a link sent to the user's email	Magic Links
Email OTP	Passwordless sign-in via a 6-digit code sent to the user's email	Email OTP
Passkeys	WebAuthn-based sign-in using biometrics or security keys	Passkeys
Username & Password	Sign in with a username instead of email	Username Auth
Anonymous	Guest sessions that can be upgraded to full accounts later	Anonymous Auth
Multi-Factor Auth	TOTP-based two-factor authentication as a second layer	MFA

You can enable multiple methods at the same time. For example, you might offer email/password as the primary method, social OAuth for convenience, and MFA for added security.

Enabling Methods from the Dashboard

Open the Banata dashboard and select your project.
Go to Authentication > Methods.
Toggle on the methods you want to enable.
For methods that need additional setup (like social OAuth), follow the configuration instructions in the dashboard.

Changes take effect immediately — your app's sign-in forms will reflect the enabled methods.

Enabling Methods by Code

Use the SDK to enable or disable auth methods programmatically:

import { BanataAuth } from "@banata-auth/sdk";
 
const banata = new BanataAuth({
  apiKey: process.env.BANATA_API_KEY!,
  baseUrl: "https://auth.banata.dev",
});
 
await banata.configuration.saveDashboardConfig({
  authMethods: {
    emailPassword: true,
    socialOAuth: true,
    magicLink: true,
    emailOtp: false,
    passkey: false,
    anonymous: false,
    username: false,
    twoFactor: true,
  },
});

The SDK and dashboard share the same configuration — changes in one are immediately visible in the other.

Method-Specific Settings

Some methods have additional settings you can configure:

Email & Password

await banata.configuration.saveDashboardConfig({
  emailPassword: {
    requireEmailVerification: true,  // Require email verification before sign-in
    autoSignIn: true,                // Sign in automatically after sign-up
    minPasswordLength: 8,            // Minimum password length (default: 8)
    maxPasswordLength: 128,          // Maximum password length (default: 128)
  },
});

Passkeys (WebAuthn)

Passkey configuration requires specifying your app's domain and origin. See the Passkeys guide for details.

Organizations

await banata.configuration.saveDashboardConfig({
  organizationConfig: {
    allowUserToCreateOrg: true,    // Let users create organizations
    creatorRole: "super_admin",    // Role assigned to org creator
    maxOrganizations: 5,           // Max orgs per user (optional)
  },
});

Authorization Configuration

In addition to authentication methods, you can configure authorization behavior:

Setting	Default	Description
Multiple roles	`false`	Allow users to hold multiple roles within an organization
Role assignment	`false`	Allow mapping IdP groups to Banata roles (for SSO users)
API key permissions	`false`	Scope API keys with specific permissions

Multiple Roles

By default, each user has one role per organization. When multiple roles is enabled, users can hold several roles simultaneously, and permission checks combine all permissions from all assigned roles:

typescript

User "jane@acme.com" in Acme Corp:
  Role: developer  → code:read, code:write, deploy:staging
  Role: reviewer   → code:review, deploy:approve
 
Effective permissions: code:read, code:write, code:review, deploy:staging, deploy:approve

Configuring via Dashboard

Navigate to Authorization > Configuration in the dashboard to toggle these settings.

Configuring via SDK

// Get current authorization config
const config = await banata.configuration.getAuthConfiguration();
 
// Update authorization settings
await banata.configuration.saveAuthConfiguration({
  multipleRoles: true,
  roleAssignment: true,
  apiKeyPermissions: false,
});

Email Configuration

If you're using any email-based auth method (email/password, magic links, email OTP), you need to configure email delivery:

Set up an email provider — Go to Emails > Providers in the dashboard and configure a provider (Resend, SendGrid, etc.).
Enable email types — Under Emails > Configuration, enable the email types you need (verification, password reset, magic link, OTP, invitations).
Customize templates — Under Email Templates, customize the content and branding of each email type.

See the Emails and Email Templates guides for more details.

Next Steps

Choose the auth methods you want to add to your app:

Email & Password — The most common starting point
Social OAuth — Add Google, GitHub, and other providers
Magic Links — Passwordless sign-in via email links
Email OTP — Passwordless sign-in via email codes
Passkeys — Biometric and security key authentication