Projects

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:

Environment Separation

For production systems, use separate projects for development, staging, and production. Each environment should have its own API keys, domains, redirect URLs, OAuth apps, email or SMS providers, webhook endpoints, and secrets.

Before onboarding customers, verify:

• the final production service name and auth domains have been recorded
• the production project does not reuse development or staging secrets
• production, staging, and development run on separate deployments and databases
• redirect URLs and trusted origins match only the intended environment
• provider setup checklists are complete for every enabled auth method
• API key rotation works without exposing the raw key after creation
• audit export, status reporting, and data retention policies are documented

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.

Auth Clients

A project can have more than one relying application. Each auth client records the app-specific clientId, display name, type, redirect URIs, trusted origins, allowed audiences, and enabled auth methods.

Use separate auth clients when one project serves different application surfaces, such as:

• a customer web app
• a mobile app
• a desktop companion app
• a POS terminal
• a backend service

Keep redirect URIs and trusted origins narrow. A customer web app should not share callback URLs with the dashboard, a mobile app, or a staging deployment. Audience values should match the app that will consume the token, and consumer apps should reject tokens for any other audience.

// 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:

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

• API Keys — How to create and manage project-scoped API keys
• Project Structure — What files to add to your app
• Quick Start — Set up your first app