SDK Reference

@banata-auth/sdk is the dashboard-first Banata package.

It is a remote HTTP client for Banata auth endpoints. It does not talk to your database directly and it does not require self-hosting.

Start by creating a project and a project-scoped API key in the Banata dashboard. The SDK is the app-side client for that dashboard-managed project.

npm install @banata-auth/sdk

Initialization

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

BanataAuthOptions

What The SDK Is For

Use the SDK when your app needs to manage Banata remotely:

• users
• organizations
• SSO
• directory sync
• webhooks
• RBAC
• projects
• vault secrets
• audit logs

This is the package that should feel closest to WorkOS.

Example

import { BanataAuth } from "@banata-auth/sdk";
 
const banata = new BanataAuth({
  apiKey: process.env.BANATA_AUTH_API_KEY!,
  baseUrl: process.env.BANATA_AUTH_BASE_URL!,
});
 
const users = await banata.users.listUsers({ limit: 20 });
 
const webhook = await banata.webhooks.createEndpoint({
  url: "https://example.com/api/webhooks",
  eventTypes: ["user.created"],
});
 
const role = await banata.rbac.createRole({
  name: "HR Admin",
  slug: "hr_admin",
  permissions: ["employee.read", "employee.manage", "leave.approve"],
});
 
await banata.rbac.updateRole({
  id: role.id,
  permissions: ["employee.read", "employee.manage", "leave.approve", "payroll.read"],
});

RBAC Workflow

For RBAC, the SDK now supports the complete custom-role flow:

1. Create permission slugs with banata.rbac.createPermission(...)
2. Create a role with an initial permissions array, or create it empty
3. Update that role later with banata.rbac.updateRole({ id, permissions: [...] })
4. Assign the role slug to an organization member with banata.rbac.assignRole(...)
5. Check access with banata.rbac.checkPermission(...) or checkPermissions(...)

This matches the dashboard flow on /authorization/roles and /authorization/permissions.

Resource Groups

Error Handling

SDK responses throw typed errors from @banata-auth/shared:

import { AuthenticationError, NotFoundError } from "@banata-auth/shared";
 
try {
  await banata.users.getUser("usr_123");
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API key");
  }
 
  if (error instanceof NotFoundError) {
    console.error("User not found");
  }
}

Positioning

• Use @banata-auth/sdk for the public, dashboard-first integration story.
• Create the project and issue the API key in the dashboard first. The SDK then operates inside that API key's project scope.
• Use @banata-auth/convex only when you intentionally want the self-hosted runtime.