Banata

Start Here

Projects

Projects are the isolation boundary in Banata Auth. Each project has its own users, organizations, roles, and configuration.

A project is the fundamental unit of isolation in Banata Auth. Everything — users, sessions, organizations, roles, providers, email templates, branding, and more — lives inside a project. When your app connects to Banata with an API key, it's connected to one specific project.

What a Project Contains

Each project is a completely independent auth environment with its own:

  • Users and sessions — user accounts, active sessions, and credentials
  • Organizations — workspaces, teams, and their members
  • Roles and permissions — the RBAC catalog for that project
  • Auth methods — which sign-in methods are enabled (email/password, social OAuth, etc.)
  • Provider credentials — OAuth client IDs and secrets for social providers
  • Email configuration — email provider, templates, and delivery settings
  • Branding — colors, logo, fonts, and other visual customization
  • Enterprise features — SSO connections, SCIM directories, audit logs, webhooks
  • API keys — the keys that connect apps to this project

If you have two apps using two different projects, their data is completely separate. A user in project A does not exist in project B.

When to Use Multiple Projects

One project per application is the most common setup. But there are good reasons to use multiple projects:

ScenarioApproach
One app, one environmentSingle project
Separate staging and productionOne project per environment
Multiple apps with shared usersSingle project, shared by both apps
Multiple apps with separate usersOne project per app
White-label / multi-tenant platformOne project per tenant

Your Default Project

When you first sign in to the Banata dashboard, a default project is automatically created for you. This is your starting point — you can use it immediately or create additional projects as needed.

The default project is tied to your dashboard admin account. It's not a global shared project — each dashboard admin gets their own default project on first login.

Switching Projects in the Dashboard

The project switcher in the dashboard lets you navigate between your projects. When you switch projects, the entire dashboard context changes — the users list, organizations, roles, providers, email templates, and everything else reflects the selected project.

How Your App Connects to a Project

Your app connects to a project through an API key:

  1. You create an API key in the dashboard, scoped to a specific project.
  2. You add the key to your app's server environment as BANATA_API_KEY.
  3. Banata resolves the project from the key automatically.

You never need to pass a projectId in your app code for normal usage. The API key handles project binding.

ts
// The API key determines which project this app uses
export const { handler } = createBanataAuthServer({
  apiKey: process.env.BANATA_API_KEY!, // ← This binds to your project
  authUrl: process.env.BANATA_AUTH_URL,
});

Managing Projects with the SDK

You can list and manage projects programmatically using the admin SDK:

ts
import { BanataAuth } from "@banata-auth/sdk";
 
const banata = new BanataAuth({
  apiKey: process.env.BANATA_API_KEY!,
  baseUrl: "https://auth.banata.dev",
});
 
// List projects accessible with this key
const projects = await banata.projects.listProjects();

For most apps, the dashboard is the primary way to manage projects. The SDK is useful for automation or platform-level tooling.

Next Steps