Package Exports
- better-auth-rbac
- better-auth-rbac/client
Readme
Better Auth RBAC Plugin
A flexible Role-Based Access Control (RBAC) plugin for Better Auth that provides fine-grained permission management.
Features
- Role-based permission management
- Granular access control
- Easy integration with Better Auth
- Built-in user impersonation
- Ban/unban user management
- Session management
- Default role assignment
Installation
npm install better-auth-rbac
Basic Usage
Server Configuration
import { rbac } from 'better-auth-rbac';
import { betterAuth } from "better-auth";
const auth = betterAuth({
plugins: [
rbac()
]
});
Client Configuration
import { rbacClient } from "better-auth-rbac/client";
export const authClient = createAuthClient({
plugins: [
rbacClient()
]
});
Permission Checks
// Check permissions by IDs
const hasAccess = auth.api.hasPermission({
body: {
permissionIds: ['1', '2', '3'],
userId: "1", // Optional: Check specific user
roleId: '1' // Optional: Check specific role
}
});
// Check permissions by resource/action mapping
const hasAccess = auth.api.hasPermission({
body: {
permissions: {
user: ["read", "create"],
post: ["read"]
},
userId: "1"
}
});
Customisation
import { rbac } from 'better-auth-rbac';
import { betterAuth } from "better-auth";
// Initialize Better Auth with RBAC plugin
const auth = betterAuth({
plugins: [
rbac({
// Optional configuration
defaultRoleId: '2', // Default role ID for new users
adminRoleIds: ['1'], // Array of admin role IDs
bannedUserMessage: "Custom ban message", // Custom message for banned users
impersonationSessionDuration: 3600, // Duration in seconds for impersonation sessions
// Resource permissions (optional overrides)
resourcePermissions: {
user: {
get: "fetchUser",
update: "modifyUser"
},
session: {
revoke: "kill_session"
}
},
// Custom permission check (optional)
hasPermission: async (input, adapter) => {
// Admin roles bypass permission checks
if (input.options?.adminRoleIds?.includes(input.roleId)) {
return true;
}
if (input.permissionIds) {
// Using your own drizzle db;
const permissionsList = await db.query.permissions.findMany({
with: {
rolePermissions: {
where: (rolePerms, { eq }) => eq(rolePerms.id, input.roleId)
}
},
where: (perms, { inArray }) => inArray(perms.id, input.permissionIds),
});
return permissionsList.length > 0;
}
return false;
}
})
]
});
API Reference
Core Endpoints
Endpoint | Method | Description |
---|---|---|
/admin/has-permission |
POST | Check if a user/role has specific permissions |
/admin/:roleId/role-permissions |
GET | List permissions for a role |
/admin/update-role-permission |
POST | Update role permissions |
/admin/set-role |
POST | Set a user's role |
User Management
Endpoint | Method | Description |
---|---|---|
/admin/create-user |
POST | Create a new user |
/admin/update-user |
POST | Update user details |
/admin/remove-user |
POST | Delete a user |
/admin/set-user-password |
POST | Set user's password |
/admin/ban-user |
POST | Ban a user |
/admin/unban-user |
POST | Unban a user |
Session Management
Endpoint | Method | Description |
---|---|---|
/admin/list-user-sessions |
POST | List user's sessions |
/admin/revoke-user-session |
POST | Revoke specific session |
/admin/revoke-user-sessions |
POST | Revoke all user sessions |
/admin/impersonate-user |
POST | Impersonate a user |
/admin/stop-impersonating |
POST | Stop user impersonation |
User Operations
Endpoint | Method | Description |
---|---|---|
/admin/get-user |
GET | Get user details |
/admin/list-users |
GET | List users with filtering and pagination |
License
ISC