API Keys

An API key is the link between your application and a Banata project. Every request your app makes to Banata carries this key, which tells Banata two things: that your app is authorized, and which project it belongs to.

Creating an API Key

1. Sign in to the Banata dashboard.
2. Select the project you want to connect your app to.
3. Go to API Keys in the sidebar.
4. Click Create new key.
5. Copy the key immediately and store it securely.

Important: The full API key is only displayed once at creation time. Banata stores a hash of the key, not the raw value, so it cannot be retrieved later. If you lose it, create a new one.

Using Your API Key

In a Next.js app

Pass the API key to createBanataAuthServer in your server auth helpers:

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

If authUrl is omitted, hosted Banata integrations default to https://auth.banata.dev.

With the admin SDK

Pass the API key when creating a BanataAuth client:

import { BanataAuth } from "@banata-auth/sdk";
 
const banata = new BanataAuth({
  apiKey: process.env.BANATA_API_KEY!,
  baseUrl: "https://auth.banata.dev",
});

In both cases, the API key is a server-side secret. Never expose it to the browser or include it in client-side code.

How Project Scoping Works

Each API key belongs to exactly one project. When your app sends a request with that key, Banata automatically scopes the request to the correct project. You don't need to pass a projectId in your code — the key handles that.

This means:

• Users created through your app belong to that project.
• Organizations, roles, and configurations are all scoped to that project.
• An API key from project A cannot access data in project B.

Security Best Practices

Store keys in environment variables

Never hard-code API keys in your source code. Use environment variables or a secrets manager:

# .env.local (never commit this file)
BANATA_API_KEY=sk_live_your_project_key

Use separate keys for separate concerns

If you have multiple services connecting to the same project (e.g., your web app and a background job worker), create a separate API key for each. This way, if one key is compromised, you can revoke it without affecting the others.

Rotate keys regularly

To rotate an API key safely:

1. Create a new key in the dashboard.
2. Deploy your app with the new key.
3. Verify everything works with the new key.
4. Revoke the old key in the dashboard.

Managing API Keys with the SDK

You can also create and manage API keys programmatically:

import { BanataAuth } from "@banata-auth/sdk";
 
const banata = new BanataAuth({
  apiKey: process.env.BANATA_API_KEY!,
  baseUrl: "https://auth.banata.dev",
});
 
// Create a new API key
const key = await banata.apiKeys.createKey({
  name: "Production Web App",
});
 
// List all keys for the project
const keys = await banata.apiKeys.listKeys();
 
// Delete a key
await banata.apiKeys.deleteKey({ keyId: key.id });

Troubleshooting

Auth requests work in the dashboard but fail in the app

• Verify BANATA_API_KEY is set in your server environment (not just .env.local — check your deployment platform too).
• Make sure you're using the correct key for the right project.

Requests return data from the wrong project

• You may be using an API key from a different project. Check which project the key was created in.

Key works locally but not in production

• Confirm the production deployment has the correct BANATA_API_KEY environment variable.
• If you recently created the key, make sure the production Banata backend has been redeployed.

Next Steps

• Projects — Understand how projects provide data isolation
• Quick Start — Set up your first app with Banata
• SDK Reference — Manage API keys and other resources programmatically