- Updated: March 22, 2026
- 9 min read
Implementing Role‑Based Access Control (RBAC) in the OpenClaw Full‑Stack Template
Implementing Role‑Based Access Control (RBAC) in the OpenClaw full‑stack template means defining a clear set of roles, mapping each role to specific permissions, and protecting your API routes with a lightweight Node.js middleware that checks the current user’s role before allowing access.
1. Introduction
OpenClaw is UBOS’s flagship full‑stack starter kit, offering a ready‑made backend, frontend, and DevOps pipeline. While it accelerates development, security remains a top priority for developers, DevOps engineers, and tech entrepreneurs building SaaS or enterprise applications. Adding RBAC to OpenClaw gives you granular control over who can read, write, or administer resources, reducing the attack surface and simplifying compliance.
In this guide we’ll walk through the RBAC concepts, show you step‑by‑step code examples for defining roles, assigning them to users, and protecting API routes with middleware—all within the OpenClaw template. By the end you’ll have a production‑ready access‑control layer you can extend as your product grows.
2. What is RBAC?
Role‑Based Access Control (RBAC) is a security paradigm that restricts system access to authorized users based on their assigned roles. Each role aggregates a set of permissions, and users inherit those permissions through role membership. This approach is:
- Scalable – Adding a new permission only requires updating the role definition.
- Auditable – Permissions are centrally managed, making compliance checks straightforward.
- Maintainable – Business logic stays clean because access checks are abstracted away from core code.
For a deeper dive, see the Wikipedia article on RBAC.
3. Benefits of RBAC in OpenClaw
Integrating RBAC into OpenClaw brings several concrete advantages:
- Unified security model across the backend API and the React‑based admin UI.
- Zero‑trust defaults – Unauthenticated requests are denied unless explicitly allowed.
- Fast onboarding – New team members receive a role that matches their responsibilities without manual permission tweaking.
- Future‑proofing – As you expand to multi‑tenant SaaS, RBAC scales to support tenant‑level roles.
These benefits align perfectly with the UBOS platform overview, which emphasizes security‑by‑design for modern web applications.
4. Defining Roles and Permissions (code example)
OpenClaw uses a Node.js/Express backend. Let’s start by creating a simple rbac.js module that stores role definitions in a plain JavaScript object. In a production environment you’d likely persist this in a database, but the concept remains identical.
// rbac.js
const roles = {
admin: {
can: [
'user:create',
'user:read',
'user:update',
'user:delete',
'project:create',
'project:read',
'project:update',
'project:delete'
]
},
manager: {
can: [
'project:create',
'project:read',
'project:update',
'project:delete'
]
},
viewer: {
can: ['project:read']
}
};
/**
* Checks if a role has a specific permission.
* @param {string} role - Role name (e.g., 'admin')
* @param {string} permission - Permission string (e.g., 'project:create')
* @returns {boolean}
*/
function can(role, permission) {
const roleDef = roles[role];
if (!roleDef) return false;
return roleDef.can.includes(permission);
}
module.exports = { roles, can };
Notice the can helper – it abstracts the permission lookup, keeping your route handlers clean. You can extend the roles object with more granular permissions (e.g., resource‑level scopes) as your application evolves.
5. Assigning Roles to Users (code example)
OpenClaw ships with a User model based on Sequelize. Add a role column to the model and expose an endpoint for role assignment.
// models/user.js (excerpt)
module.exports = (sequelize, DataTypes) => {
const User = sequelize.define('User', {
email: { type: DataTypes.STRING, unique: true, allowNull: false },
passwordHash: { type: DataTypes.STRING, allowNull: false },
// New column for RBAC
role: { type: DataTypes.ENUM('admin', 'manager', 'viewer'), defaultValue: 'viewer' }
});
return User;
};
Now create a protected route that only admins can call to change a user’s role:
// routes/admin.js
const express = require('express');
const router = express.Router();
const { User } = require('../models');
const { can } = require('../rbac');
const { authenticate } = require('../middleware/auth');
// Middleware that checks RBAC permission
function authorize(permission) {
return (req, res, next) => {
const userRole = req.user.role; // set by authenticate
if (can(userRole, permission)) return next();
return res.status(403).json({ error: 'Forbidden' });
};
}
// Assign role endpoint
router.put('/users/:id/role',
authenticate,
authorize('user:update'), // only roles with this permission can change roles
async (req, res) => {
const { role } = req.body;
if (!['admin', 'manager', 'viewer'].includes(role)) {
return res.status(400).json({ error: 'Invalid role' });
}
const user = await User.findByPk(req.params.id);
if (!user) return res.status(404).json({ error: 'User not found' });
user.role = role;
await user.save();
res.json({ message: 'Role updated', user: { id: user.id, role: user.role } });
});
module.exports = router;
This snippet demonstrates three key ideas:
- The
authenticatemiddleware (provided by OpenClaw) populatesreq.user. - The custom
authorizemiddleware reuses thecanhelper to enforce RBAC. - Only users whose role includes
user:updatecan modify another user’s role.
For a visual overview of how OpenClaw’s authentication flow works, check the OpenClaw hosting page.
6. Protecting API Routes with Middleware (code example)
Beyond admin‑only endpoints, most business APIs need role‑specific protection. Below is a generic rbacMiddleware you can drop into any route file.
// middleware/rbac.js
const { can } = require('../rbac');
/**
* Returns an Express middleware that checks a permission.
* @param {string} permission - e.g., 'project:create'
*/
function rbacMiddleware(permission) {
return (req, res, next) => {
const role = req.user?.role;
if (!role) return res.status(401).json({ error: 'Unauthenticated' });
if (can(role, permission)) return next();
return res.status(403).json({ error: 'Insufficient permissions' });
};
}
module.exports = { rbacMiddleware };
Apply it to a typical CRUD controller:
// routes/projects.js
const express = require('express');
const router = express.Router();
const { Project } = require('../models');
const { authenticate } = require('../middleware/auth');
const { rbacMiddleware } = require('../middleware/rbac');
// Create a project – only admins & managers
router.post('/',
authenticate,
rbacMiddleware('project:create'),
async (req, res) => {
const project = await Project.create({ ...req.body, ownerId: req.user.id });
res.status(201).json(project);
});
// Read a project – any authenticated user (viewer role)
router.get('/:id',
authenticate,
rbacMiddleware('project:read'),
async (req, res) => {
const project = await Project.findByPk(req.params.id);
if (!project) return res.status(404).json({ error: 'Not found' });
res.json(project);
});
// Update a project – admins & managers
router.put('/:id',
authenticate,
rbacMiddleware('project:update'),
async (req, res) => {
const project = await Project.findByPk(req.params.id);
if (!project) return res.status(404).json({ error: 'Not found' });
await project.update(req.body);
res.json(project);
});
// Delete a project – admins only
router.delete('/:id',
authenticate,
rbacMiddleware('project:delete'),
async (req, res) => {
const project = await Project.findByPk(req.params.id);
if (!project) return res.status(404).json({ error: 'Not found' });
await project.destroy();
res.json({ message: 'Deleted' });
});
module.exports = router;
Notice how the same rbacMiddleware is reused across all CRUD actions, keeping the route files concise and readable.
7. Testing the RBAC implementation
Automated tests guarantee that permission changes don’t break existing functionality. Below is a Jest test suite that validates the middleware for the /projects endpoints.
// __tests__/rbac.test.js
const request = require('supertest');
const app = require('../app'); // Express app
const { User, Project } = require('../models');
let adminToken, managerToken, viewerToken;
beforeAll(async () => {
// Create users with different roles
const admin = await User.create({ email: 'admin@example.com', passwordHash: 'hash', role: 'admin' });
const manager = await User.create({ email: 'manager@example.com', passwordHash: 'hash', role: 'manager' });
const viewer = await User.create({ email: 'viewer@example.com', passwordHash: 'hash', role: 'viewer' });
// Assume a login endpoint that returns JWT
const adminRes = await request(app).post('/auth/login').send({ email: admin.email, password: 'pwd' });
const managerRes = await request(app).post('/auth/login').send({ email: manager.email, password: 'pwd' });
const viewerRes = await request(app).post('/auth/login').send({ email: viewer.email, password: 'pwd' });
adminToken = adminRes.body.token;
managerToken = managerRes.body.token;
viewerToken = viewerRes.body.token;
});
test('Admin can delete a project', async () => {
const proj = await Project.create({ name: 'Test', ownerId: 1 });
const res = await request(app)
.delete(`/projects/${proj.id}`)
.set('Authorization', `Bearer ${adminToken}`);
expect(res.statusCode).toBe(200);
});
test('Manager cannot delete a project', async () => {
const proj = await Project.create({ name: 'Test2', ownerId: 1 });
const res = await request(app)
.delete(`/projects/${proj.id}`)
.set('Authorization', `Bearer ${managerToken}`);
expect(res.statusCode).toBe(403);
});
test('Viewer can read a project', async () => {
const proj = await Project.create({ name: 'ReadOnly', ownerId: 1 });
const res = await request(app)
.get(`/projects/${proj.id}`)
.set('Authorization', `Bearer ${viewerToken}`);
expect(res.statusCode).toBe(200);
});
Running this suite with npm test will confirm that:
- Admins have full CRUD rights.
- Managers lack delete permission.
- Viewers can only read.
Integrate these tests into your CI pipeline (GitHub Actions, GitLab CI, etc.) to catch regressions early.
8. Conclusion and Next Steps
By following the steps above you now have a robust RBAC layer inside the OpenClaw full‑stack template. The implementation is:
- Modular – role definitions live in a single file.
- Reusable – the
rbacMiddlewarecan protect any future endpoint. - Tested – automated Jest tests verify permission boundaries.
- Scalable – you can extend roles, add resource‑level scopes, or integrate with external identity providers.
What’s next?
- Persist roles in the database – Create a
Rolemodel and a many‑to‑many relationship withUserfor dynamic role management. - Introduce attribute‑based access control (ABAC) – Combine RBAC with context (e.g., project ownership) for finer granularity.
- Leverage UBOS AI tools – Use the AI marketing agents to generate documentation for your new security layer automatically.
- Explore the Template Marketplace – Jump‑start related features with ready‑made templates like the GPT‑Powered Telegram Bot or the AI SEO Analyzer.
- Review pricing – If you need higher‑tier resources for heavy traffic, compare the UBOS pricing plans to find the best fit.
Implementing RBAC is a foundational security step that pays dividends as your product scales. The OpenClaw template, backed by the UBOS team, gives you the scaffolding; RBAC gives you the guardrails.
“Security isn’t a feature you add later – it’s the architecture you build from day one.” – UBOS Engineering Lead
Andrii Bidochko
CTO UBOS
Andrii Bidochko is an AI entrepreneur and researcher focused on AI agents, reinforcement learning, and autonomous systems. He writes about the technologies shaping the future of machine intelligence, from frontier models and agent architectures to real-world AI applications.