Roles & Permissions

Banata Auth uses a super-admin-first RBAC model for organizations.

• Every new project is seeded with exactly one visible default role: super_admin.
• Organizations are created explicitly; when an organization is created, its creator is assigned super_admin.
• Customers then create any additional roles and permissions they need.

Role Model

Visible default role

Reserved role slugs

The following role slugs are reserved:

• super_admin

Custom roles cannot use these reserved slugs.

Permission Model

Permissions are project-scoped and shared by all organizations in that project.

Two categories:

1. Built-in permissions (seeded automatically)
   • examples: organization.read, member.invite, role.create, api_key.create, sandbox.create, browser.connect, billing.manage
2. Custom permissions (created by customers)
   • examples: document.publish, workspace.archive, model.deploy

Built-in permissions are protected and cannot be deleted.

Bootstrap Behavior

When a project is created (or default project is ensured):

1. Built-in permissions are seeded.
2. super_admin role is created (if missing).
3. super_admin is linked to all built-in permissions.
4. Organizations can then be created explicitly from the dashboard or API.
5. The creator of each organization is assigned super_admin for that organization.

Dashboard Management

Use the dashboard in this order:

1. Open /authorization/permissions
2. Create the permission slugs your app will check, for example:
   • employee.read
   • employee.manage
   • leave.approve
   • payroll.read
3. Open /authorization/roles
4. Create a custom role such as hr_admin or manager
5. From the role row, click Manage permissions
6. On /authorization/permissions?role=<role-slug>, toggle the permission slugs that role should grant
7. Save the role-permission assignment
8. Open the organization member screen and assign that role slug to members

What is editable:

• custom roles can be created, updated, and deleted
• custom permissions can be created, updated, and deleted
• custom roles can have permission slugs assigned directly from the permissions screen

What stays protected:

• super_admin role cannot be deleted or edited
• built-in permissions cannot be deleted or edited

Important protections:

• role assignment is organization-scoped
• role and permission catalogs are project-scoped
• permission checks should still be enforced on your server for sensitive actions

SDK (@banata-auth/sdk)

import { BanataAuth } from "@banata-auth/sdk";
 
const banata = new BanataAuth({
  apiKey: "sk_live_...",
  baseUrl: "https://your-deployment.convex.site",
});

Roles

const roles = await banata.rbac.listRoles();
 
const role = await banata.rbac.createRole({
  name: "Sandbox Operator",
  slug: "sandbox_operator",
  description: "Can manage runtime sandboxes",
  permissions: ["sandbox.create", "browser.connect"],
});
 
const updatedRole = await banata.rbac.updateRole({
  id: role.id,
  permissions: ["sandbox.create", "browser.connect", "browser.launch"],
});
 
await banata.rbac.deleteRole(role.id);

Permissions

const permissions = await banata.rbac.listPermissions();
 
const permission = await banata.rbac.createPermission({
  name: "Terminate browser session",
  slug: "browser.terminate",
  description: "Allows terminating running browser sessions",
});
 
const updatedPermission = await banata.rbac.updatePermission({
  id: permission.id,
  name: "Terminate browser",
  slug: "browser.terminate",
  description: "Allows terminating running browser sessions",
});
 
await banata.rbac.deletePermission(permission.id);

Assign or Revoke Roles

await banata.rbac.assignRole({
  organizationId: "org_01...",
  userId: "usr_01...",
  role: "sandbox_operator",
});
 
await banata.rbac.revokeRole({
  organizationId: "org_01...",
  userId: "usr_01...",
  fallbackRole: "super_admin",
});

Permission Checks

Permission checks are project-scoped. You can pass a full slug string or { resource, action }.

const canLaunch = await banata.rbac.checkPermission({
  projectId: "proj_01...",
  permission: { resource: "sandbox", action: "create" },
});
 
const canOperate = await banata.rbac.checkPermissions({
  projectId: "proj_01...",
  permissions: [
    { resource: "sandbox", action: "create" },
    { resource: "browser", action: "connect" },
  ],
  operator: "all",
});

API Endpoints

Role and permission management endpoints:

• POST /api/auth/banata/config/roles/list
• POST /api/auth/banata/config/roles/create
• POST /api/auth/banata/config/roles/update
• POST /api/auth/banata/config/roles/delete
• POST /api/auth/banata/config/permissions/list
• POST /api/auth/banata/config/permissions/create
• POST /api/auth/banata/config/permissions/update
• POST /api/auth/banata/config/permissions/delete

Role assignment endpoint:

• POST /api/auth/organization/update-member-role

Best Practices

1. Keep super_admin limited to trusted org owners.
2. Prefer capability-based roles (for example sandbox_operator, billing_viewer) over generic titles.
3. Keep permissions granular and explicit (resource.action style slugs).
4. Use server-side checks for all sensitive actions.

What's Next

• Organizations
• Auth Configuration
• Resource Types