Users & RBAC

Cloud OS supports multiple user accounts with role-based access control (RBAC). Three built-in roles provide graduated levels of access, and all user actions are tracked in an audit log.

Built-in Roles

Role	Access Level	Can Do	Cannot Do
Admin	Full access	Everything — manage users, change settings, install/remove apps, create backups, configure VPN, view audit logs	N/A
Operator	Operational access	Manage apps (install, start, stop, restart, update), view monitoring, create backups, manage domains	Cannot manage users, change system settings, or view security configuration
Viewer	Read-only access	View dashboard, monitoring charts, app status, and backup history	Cannot modify anything — all write actions are disabled

Permission enforcement happens at the API level. Unauthorized requests return a 403 Forbidden response regardless of how they are made (UI, CLI, or direct API call).

User Management

Navigate to Settings > Users to manage user accounts. Admin users can:

View all users with their role and status
Invite new users
Edit user roles
Disable or delete user accounts
Manage individual user sessions

User Invitations

Click Invite User
Enter the user email address
Select a role (Admin, Operator, or Viewer)
Click Send Invitation

The invited user receives an email with a setup link where they create a password and optionally enable 2FA. The invitation expires after 72 hours.

If email is not configured, you can share the invitation link manually. It is displayed in the UI after creating the invitation.

Two-Factor Authentication (2FA)

Cloud OS supports TOTP-based 2FA compatible with Google Authenticator, Authy, and similar apps.

Enabling 2FA

Go to Settings > Security
Click Enable 2FA
Scan the QR code with your authenticator app
Enter the 6-digit code to verify
Save the backup codes in a secure location

Backup Codes

During 2FA setup, Cloud OS generates a set of one-time backup codes. These can be used to log in if you lose access to your authenticator app. Each code can only be used once.

Store backup codes securely. If you lose both your authenticator device and backup codes, an Admin user will need to disable 2FA on your account.

Enforcing 2FA

Admins can require 2FA for all users in Settings > Security > Require 2FA. When enabled, users without 2FA are prompted to set it up on their next login.

Session Management

Each user can view and manage their active sessions from Settings > Security > Sessions. A session entry shows:

Browser and operating system
IP address
Last activity time
Creation time

Click Revoke next to any session to immediately invalidate it. Admins can view and revoke sessions for any user from the user management page.

API Keys

Users can generate API keys for programmatic access to the Cloud OS REST API.

Key Format

API keys use the qzr_ prefix followed by a unique identifier:


qzr_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Key Authentication

API keys are validated using HMAC-SHA256. Include the key in the Authorization header:


Authorization: Bearer qzr_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Managing API Keys

Navigate to Settings > API Keys to:

Generate new keys with a descriptive label
Set key expiration dates
Revoke existing keys
View key usage history

API keys inherit the permissions of the user who created them.

Activity and Audit Logging

Cloud OS records all user actions in an audit log accessible from Settings > Users > Activity. Each log entry includes:

Field	Description
Timestamp	When the action occurred
User	Who performed the action
Action	What was done (e.g., “Installed Nextcloud”, “Stopped Grafana”)
Resource	The affected resource (app, user, backup, etc.)
IP Address	The IP the user connected from
User Agent	The browser or CLI used

Filtering the Activity Log

Use the filters at the top of the activity log to narrow results:

User — show actions from a specific user
Action type — filter by category (app, auth, backup, settings, etc.)
Date range — show activity within a specific time period

Troubleshooting

Invited user did not receive the email

Check your SMTP configuration in Settings > Notifications. Send a test email to verify the SMTP settings work. Also check the invited user spam folder.

User cannot access a feature

Verify the user role. Operators cannot access user management or system settings. Viewers have read-only access. Check the role assignment in Settings > Users.

2FA code is incorrect

TOTP codes are time-based. Ensure the authenticator device clock is synchronized. A drift of more than 30 seconds will cause codes to fail. If the user is locked out, an Admin can disable 2FA on their account from the user management page.

API key returns 401 Unauthorized

Verify the key has not expired or been revoked. Check that the Authorization header format is correct. API keys inherit user permissions, so the key owner must have access to the requested endpoint.