Skip to main content

RBAC & User Management

Configure users, roles, and permissions for your Bloqd installation.

User Roles​

Bloqd has three built-in roles with predefined permissions:

RoleDescriptionUse Case
ViewerRead-only accessMonitoring, reporting
OperatorManage bans and serversDay-to-day operations
AdminFull accessSystem administration

Permission Matrix​

PermissionViewerOperatorAdmin
View dashboard✓✓✓
View servers✓✓✓
View bans✓✓✓
View whitelist✓✓✓
View templates✓✓✓
Ban/unban IPs✓✓
Edit whitelist✓✓
Deploy templates✓✓
Add/remove servers✓
Manage users✓
System settings✓
API key management✓
Terminal access✓

Managing Users​

Create User​

  1. Go to Settings → Users
  2. Click Add User
  3. Fill in details:
    • Username
    • Email
    • Password
    • Role
  4. Click Create

Edit User​

  1. Go to Settings → Users
  2. Find user in list
  3. Click Edit
  4. Modify details
  5. Click Save

Delete User​

  1. Go to Settings → Users
  2. Find user in list
  3. Click Delete
  4. Confirm deletion
warning

You cannot delete your own account or the last admin user.

Reset Password​

  1. Go to Settings → Users
  2. Find user
  3. Click Reset Password
  4. New password is generated/emailed

Multi-Factor Authentication​

Enable MFA for User​

  1. Go to Profile (as user)
  2. Click Security
  3. Click Enable MFA
  4. Scan QR code with authenticator app
  5. Enter verification code
  6. Save backup codes

Require MFA for All Users​

  1. Go to Settings → Security
  2. Enable Require MFA
  3. Set grace period for existing users
  4. Save

MFA Recovery​

If user loses MFA device:

  1. Admin goes to Settings → Users
  2. Find user
  3. Click Reset MFA
  4. User can set up MFA again

API Keys​

Create API Key​

  1. Go to Settings → API Keys
  2. Click Create Key
  3. Configure:
    • Name
    • Permissions (role-based or custom)
    • Expiration (optional)
  4. Copy key (shown only once)

API Key Permissions​

API keys can have:

  • Role-based permissions (Viewer, Operator, Admin)
  • Custom scoped permissions
ScopeDescription
servers:readView servers
servers:writeManage servers
bans:readView bans
bans:writeBan/unban IPs
whitelist:readView whitelist
whitelist:writeEdit whitelist
templates:readView templates
templates:writeManage templates
users:readView users
users:writeManage users
settings:readView settings
settings:writeModify settings

Revoke API Key​

  1. Go to Settings → API Keys
  2. Find key
  3. Click Revoke
  4. Confirm

Server-Level Permissions​

Pro Feature

Server-level RBAC requires a Pro license.

Restrict users to specific servers:

Assign Servers to User​

  1. Go to Settings → Users
  2. Edit user
  3. Under Server Access:
    • Select All Servers or
    • Choose specific servers
  4. Save

Per-Server Roles​

Assign different roles per server:

{
  "userId": "user-uuid",
  "serverPermissions": {
    "server1-uuid": "admin",
    "server2-uuid": "operator",
    "server3-uuid": "viewer"
  }
}

Session Management​

View Active Sessions​

  1. Go to Settings → Security
  2. Click Active Sessions
  3. See all logged-in sessions

Terminate Session​

  1. Find session in list
  2. Click Terminate
  3. User is logged out immediately

Session Settings​

SettingDescriptionDefault
Session TimeoutIdle timeout24 hours
Max SessionsPer user5
Remember MeExtended session30 days

Audit Log​

All user actions are logged:

View Audit Log​

  1. Go to Settings → Audit Log
  2. Filter by:
    • User
    • Action type
    • Date range
    • Resource

Logged Actions​

CategoryActions Logged
AuthenticationLogin, logout, MFA events
UsersCreate, edit, delete users
ServersAdd, remove, configure servers
BansBan, unban actions
WhitelistAdd, remove entries
SettingsConfiguration changes
API KeysCreate, revoke keys

Export Audit Log​

curl "https://bloqd.example.com/api/v1/audit/export?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o audit-log.csv

OAuth Users​

When using OAuth (GitHub/Google):

Role Assignment​

New OAuth users get default role:

OAUTH_DEFAULT_ROLE=Viewer

Promote OAuth User​

  1. Go to Settings → Users
  2. Find OAuth user
  3. Change role
  4. Save

Users can link OAuth to existing account:

  1. Log in with local account
  2. Go to Profile → Linked Accounts
  3. Click Link GitHub or Link Google

API Usage​

List Users​

curl "https://bloqd.example.com/api/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create User​

curl -X POST "https://bloqd.example.com/api/v1/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "user@example.com",
    "password": "SecurePassword123!",
    "role": "Operator"
  }'

Update User Role​

curl -X PATCH "https://bloqd.example.com/api/v1/users/{userId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "Admin"
  }'

Delete User​

curl -X DELETE "https://bloqd.example.com/api/v1/users/{userId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Security Best Practices​

  1. Principle of least privilege - Give minimum required permissions
  2. Use MFA - Require for all users, especially admins
  3. Rotate API keys - Set expiration and rotate regularly
  4. Review audit logs - Check for suspicious activity
  5. Limit admin accounts - Few admins, more operators/viewers
  6. Use OAuth - Leverage existing identity providers
  7. Session management - Short timeouts, terminate unused sessions
  8. Server-level RBAC - Restrict access to relevant servers only

Troubleshooting​

User Can't Log In​

  1. Verify username/email
  2. Check password is correct
  3. Verify account isn't locked
  4. Check MFA if enabled

Permission Denied​

  1. Check user's role
  2. Verify server-level permissions
  3. Check API key scopes
  4. Review audit log for details

MFA Not Working​

  1. Verify time sync on device
  2. Check authenticator app
  3. Try backup codes
  4. Admin can reset MFA