RBAC Reference

Role-Based Access Control configuration.

Backflow supports two RBAC systems:

• Platform RBAC: Database-backed roles for route protection
• Tenant RBAC: Tenant-configurable roles for end-users

Tenant RBAC

Tenants can define custom roles for their end-users without database tables.

Configuration

{
  "tenantRbac": {
    "enabled": true,
    "defaultRole": "viewer",
    "roles": [
      {
        "name": "viewer",
        "description": "Read-only access",
        "permissions": ["read"]
      },
      {
        "name": "editor",
        "description": "Can create and edit",
        "permissions": ["read", "write"],
        "parentRole": "viewer"
      },
      {
        "name": "admin",
        "permissions": ["read", "write", "delete", "manage"]
      }
    ]
  }
}

SDK Usage

// Get RBAC config
const config = await bf.tenant.rbac.getConfig();

// List all roles
const roles = await bf.tenant.rbac.listRoles();

// Create a role
await bf.tenant.rbac.createRole({
  name: 'moderator',
  description: 'Content moderator',
  permissions: ['read', 'write', 'moderate']
});

// Update a role
await bf.tenant.rbac.updateRole('moderator', {
  permissions: ['read', 'write', 'moderate', 'ban']
});

// Delete a role
await bf.tenant.rbac.deleteRole('moderator');

API Endpoints

Method	Endpoint	Description
GET	/tenant/rbac	Get RBAC config
PUT	/tenant/rbac	Update RBAC config
GET	/tenant/rbac/roles	List all roles
POST	/tenant/rbac/roles	Create a role
PUT	/tenant/rbac/roles/{name}	Update a role
DELETE	/tenant/rbac/roles/{name}	Delete a role

Use with Resource Limits

Roles can be used as conditions for resource limits:

{
  "userLimits": {
    "resourceLimits": [
      {
        "resource": "llm",
        "metric": "tokens",
        "period": "day",
        "limit": 1000,
        "conditions": {
          "roles": ["viewer"]
        }
      }
    ]
  }
}

---

Platform RBAC

Database-backed RBAC for protecting routes.

Enable RBAC

{
  "rbac": {
    "enabled": true,
    "defaultRole": "user"
  }
}

Configuration Options

interface RBACConfig {
  enabled: boolean;
  defaultRole?: string;
  rolesTable?: string;        // Default: 'roles'
  permissionsTable?: string;  // Default: 'permissions'
  userRolesTable?: string;    // Default: 'user_roles'
}

Protect Routes

{
  "path": "/admin/users",
  "method": "delete",
  "requireAuth": true,
  "requiredPermissions": ["users:delete"]
}

Multiple permissions (AND):

{
  "requiredPermissions": ["users:read", "admin:access"]
}

Database Schema

Roles Table

CREATE TABLE roles (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT UNIQUE NOT NULL,
  description TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

Permissions Table

CREATE TABLE permissions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT UNIQUE NOT NULL,
  description TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

Role Permissions Table

CREATE TABLE role_permissions (
  role_id UUID REFERENCES roles(id),
  permission_id UUID REFERENCES permissions(id),
  PRIMARY KEY (role_id, permission_id)
);

User Roles Table

CREATE TABLE user_roles (
  user_id TEXT NOT NULL,
  role_id UUID REFERENCES roles(id),
  PRIMARY KEY (user_id, role_id)
);

API Endpoints

Roles

Method	Endpoint	Description
GET	/rbac/roles	List roles
POST	/rbac/roles	Create role
GET	/rbac/roles/:id	Get role
PUT	/rbac/roles/:id	Update role
DELETE	/rbac/roles/:id	Delete role

Permissions

Method	Endpoint	Description
GET	/rbac/permissions	List permissions
POST	/rbac/permissions	Create permission
DELETE	/rbac/permissions/:id	Delete permission

Assignments

Method	Endpoint	Description
POST	/rbac/assign	Assign role to user
DELETE	/rbac/unassign	Remove role from user
GET	/rbac/users/:id/roles	Get user roles
GET	/rbac/users/:id/permissions	Get user permissions

Permission Naming

Convention: resource:action

users:read
users:create
users:update
users:delete
posts:publish
admin:access
billing:manage

Check Permissions

GET /rbac/users/user-123/permissions
Authorization: Bearer <admin-token>

Response:

{
  "permissions": [
    "users:read",
    "users:create",
    "posts:read",
    "posts:create"
  ]
}

Assign Role

POST /rbac/assign
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "userId": "user-123",
  "roleId": "role-admin-uuid"
}