Copy page

API Reference

RBAC

Overview

Primebrick uses Role-Based Access Control (RBAC) with a wildcard-based permission system. Permissions are expressive, easy to reason about, and integrated with Casdoor for identity-level role mapping.

Permission format

Permissions follow a three-part dot notation:

Code
module.action.granularity

Part	Description	Examples
module	The business module	customers, billing, inventory
action	The operation	read, write, delete, export
granularity	The scope level	* (all), own (own data), team (team data)

Examples

Code
customers.read.*          # Read all customers
customers.read.own        # Read only customers you own
customers.write.*         # Create/update any customer
billing.export.team       # Export billing data for your team
inventory.delete.*        # Delete any inventory record

Wildcards

The * character acts as a wildcard and can appear in any segment:

Code
customers.*.*     # All actions on customers, all granularities
*.read.*          # Read access to every module
*.*.*             # Full access (typically admin only)

Pattern matching is performed at runtime. A user's permissions are checked against the required permission using wildcard expansion:

Code
// Required: customers.read.*
// User has: customers.read.own
// Match? No — granularity doesn't match the wildcard.

// Required: customers.read.*
// User has: customers.read.*
// Match? Yes.

Roles

Roles are collections of permissions. A role bundles together the permissions needed for a specific job function:

Role	Example permissions
viewer	*.read.own
editor	customers.read.*, customers.write.own
admin	*.*.*

Role storage

Role-to-permission mappings are stored in the database and managed via the admin UI or API. Roles are integrated with Casdoor — Casdoor manages users and their role assignments, and Primebrick syncs this information to resolve permissions at request time.

Admin bypass

Users with is_admin = true bypass all permission checks. This is an escape hatch for super-administrators and should be granted sparingly.

Code
if (user.is_admin) {
  // Permission check skipped — full access
  return next();
}

Permission enum in code

Permissions are defined as a typed enum in the codebase to prevent typos and enable IDE autocompletion:

Code
export enum Permission {
  CustomersReadAll    = 'customers.read.*',
  CustomersReadOwn    = 'customers.read.own',
  CustomersWriteAll   = 'customers.write.*',
  CustomersWriteOwn   = 'customers.write.own',
  BillingExportTeam   = 'billing.export.team',
  InventoryDeleteAll  = 'inventory.delete.*',
}

export enum Role {
  Viewer  = 'viewer',
  Editor  = 'editor',
  Admin   = 'admin',
}

Middleware checks permissions on every protected route:

Code
import { Permission, hasPermission } from '@primebrick/sdk';

router.get('/customers', requirePermission(Permission.CustomersReadAll), async (req, res) => {
  // Only reached if the user has customers.read.*
  const customers = await customerService.list();
  res.json(customers);
});

How checks work

1. The middleware extracts the JWT from the Authorization header.
2. It loads the user's roles and their associated permissions from the database.
3. If is_admin is true, the check passes immediately.
4. Otherwise, it tests each of the user's permissions against the required permission using wildcard matching.
5. If any permission matches, the request proceeds. Otherwise, a 403 Problem Details error is returned.

Next steps

• Authentication — how tokens are obtained before RBAC checks.
• Error Handling — what a permission-denied error looks like.
• Microservice Standard — how microservices enforce RBAC.