Banata

Build Your App

Next.js

Integrate Banata Auth into your Next.js app with server-side auth helpers, route proxying, and session management.

@banata-auth/nextjs is the server-side package for integrating Banata Auth into Next.js applications. It proxies auth requests through your app, keeps cookies on your domain, and provides helpers for reading auth state in server components.

bash
npm install @banata-auth/nextjs

Setup

If you haven't set up the basics yet, follow the Quick Start guide first. Here's a summary of what you need:

1. Environment Variables

bash
NEXT_PUBLIC_SITE_URL=http://localhost:3000
BANATA_API_KEY=sk_test_your_project_key
 
# Optional override for custom or self-hosted Banata auth domains.
# Hosted Banata defaults to https://auth.banata.dev
# BANATA_AUTH_URL=https://auth.yourcompany.com

2. Server Auth Helpers

ts
// src/lib/auth-server.ts
import { createBanataAuthServer } from "@banata-auth/nextjs/server";
 
export const {
  handler,
  isAuthenticated,
  getToken,
  preloadAuthQuery,
  fetchAuthQuery,
  fetchAuthMutation,
  fetchAuthAction,
} = createBanataAuthServer({
  apiKey: process.env.BANATA_API_KEY!,
  authUrl: process.env.BANATA_AUTH_URL,
});

For managed Banata, you usually do not need to pass any URL at all. createBanataAuthServer defaults to https://auth.banata.dev. Use authUrl only when you have a custom Banata auth domain or a self-hosted deployment.

3. Auth Route

ts
// src/app/api/auth/[...all]/route.ts
import { handler } from "@/lib/auth-server";
 
export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } = handler;

4. OAuth Provider Callback URLs

For managed Banata projects, register the provider callback on your Banata auth domain:

text
https://auth.banata.dev/api/auth/callback/github

If you use a custom Banata auth domain, register that domain instead:

text
https://auth.yourcompany.com/api/auth/callback/github

Your app's callbackURL in authClient.signIn.social(...) is different. That is the page Banata sends the user to after the OAuth flow is complete, for example /dashboard or /auth/callback.

If you self-host Banata instead of using the managed service, then the provider callback belongs on your own auth deployment and will usually still be /api/auth/callback/{provider} on your app/auth domain.

Server-Side Auth Helpers

Checking Authentication

Use isAuthenticated in server components and route handlers to check if the current request has a valid session:

tsx
import { redirect } from "next/navigation";
import { isAuthenticated } from "@/lib/auth-server";
 
export default async function DashboardPage() {
  const signedIn = await isAuthenticated();
 
  if (!signedIn) {
    redirect("/sign-in");
  }
 
  return <div>Welcome to the dashboard</div>;
}

Getting the Auth Token

Use getToken when you need the raw auth token for server-side API calls:

ts
import { getToken } from "@/lib/auth-server";
 
export default async function ApiPage() {
  const token = await getToken();
 
  if (!token) {
    // Not authenticated
  }
 
  // Use token for authenticated API calls
}

Fetching Data with Auth Context

If your app also uses Convex, the auth helpers let you run authenticated Convex queries and mutations from the server:

tsx
import { fetchAuthQuery } from "@/lib/auth-server";
import { api } from "@/convex/_generated/api";
 
export default async function ProfilePage() {
  const profile = await fetchAuthQuery(api.users.getProfile);
  return <div>{profile.name}</div>;
}

How the Proxy Works

When your browser calls /api/auth/sign-in/email, the Next.js route handler proxies that request to the Banata backend. The response (including session cookies) is passed back to the browser on your app's domain.

typescript
Browser → /api/auth/sign-in/email → Next.js route handler → Banata backend
                                                          ← Session cookie
Browser ← Set-Cookie on your domain ←

This approach means:

  • Cookies stay on your domain — no third-party cookie issues.
  • The API key is never exposed — the browser only talks to your app.
  • CORS is not an issue — everything is same-origin from the browser's perspective.

Programmatic Configuration

The @banata-auth/nextjs package handles transport and authentication. To change your project's configuration by code (auth methods, branding, providers), use the SDK:

ts
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,
    emailOtp: true,
  },
});

Important: your app's local auth UI or client code is not auto-discovered by Banata. Rendering a GitHub button in your app does not turn GitHub on in the dashboard by itself. Dashboard state only changes when you update it in the Banata dashboard or call the SDK configuration endpoints.

Troubleshooting

Auth calls fail with a network error

  • Check that BANATA_AUTH_URL is correct if you overrode it.
  • Verify BANATA_API_KEY is set in your environment.

No session after sign-in

  • Make sure the auth route exists at src/app/api/auth/[...all]/route.ts.
  • Verify /api/auth/get-session returns session data in your browser.
  • Ensure your app and the auth route are on the same origin.

"Do I need a projectId or clientId?"

No. The API key handles project binding automatically.

Next Steps