Reference
Roles and permissions reference
The built-in roles, what each can and cannot do, which pages and API routes need only a signed-in account, and the sign-in, MFA and session rules the server enforces.
Covers YuviRed 1.0 for Windows. Everything here is read from the server's own tables and code; the source of each fact is in the comments.
Two layers: console role and system role
The Team / Users page lets an administrator pick one of three roles for an account: Admin, Analyst or View Only. Behind those three, the server keeps five system roles, each a list of permissions. The console pick maps to a system role like this:
| Console role (Role column) | System role given | Description from the server |
|---|---|---|
| Admin | administrator | "Full operational access. Cannot manage licensing." |
| Analyst | security_analyst | "Day-to-day triage: alerts, policies, endpoints, reports." |
| View Only | read_only | "View-only access across the platform." |
| (not in the console) | super_admin | "Full access to every capability, including license and role management." |
| (not in the console) | developer | "API and integration access: AI providers, prompt templates, MCP servers." |
Three consequences to know:
- The first account is the owner (
super_admin). First-run setup creates it, and it is the only account that holds thelicense.managepermission. An account you create with the Admin role isadministratorand cannot activate a license, import a license file or redeem an activation code: the buttons show, but the request fails withMissing required permission: license.manage. Sign in with the first account to manage the license. (The license screen says: "Only a YuviRed administrator can activate this server. Sign in with the administrator account created when YuviRed was installed.") - Changing the role of an existing user replaces all of that user's role assignments with the new one.
super_adminanddeveloperand custom roles cannot be assigned from the console. They are set only through the API routePOST /api/v1/rbac/assign, which needsroles.manage. The five system roles cannot be deleted. A user with no role assignment at all is treated as the system role that matches the user's console role.
The console hides some menu items by console role (Admin only: Blocklist, Agent Deployment, Adoption Requests, Configuration, Legal, Help, Team / Users, Debug / Reset, System Logs; Analyst and Admin: Enforcement; Artifact Analysis shows only to accounts holding artifact.read). The hiding is a convenience. The server checks the permission on every request, and that check is what counts.
Permissions by role
38 permissions exist (counted from the server's permission catalogue; the "What it allows" column says where the console checks each one, which is more specific than the server's one-line description). Y means the role holds it. SA = super_admin, AD = administrator (console Admin), AN = security_analyst (console Analyst), RO = read_only (console View Only), DV = developer.
| Permission | What it allows | SA | AD | AN | RO | DV |
|---|---|---|---|---|---|---|
users.read | View user accounts | Y | Y | - | - | - |
users.manage | Create, edit, deactivate, delete users; reset passwords; turn off another user's MFA; end sessions | Y | Y | - | - | - |
roles.manage | Create and assign roles | Y | Y | - | - | - |
policies.read | View policies | Y | Y | Y | Y | - |
policies.write | Create, edit, enable or disable policies; classify AI tools | Y | Y | Y | - | - |
alerts.read | View alerts, Prompt Monitoring events and Prompt Protection policy | Y | Y | Y | Y | - |
alerts.write | Change alert status, add notes, create and change incidents, export prompt events | Y | Y | Y | - | - |
endpoints.read | Read-only endpoint extras (credential rotation status, rollout status, server identity) | Y | Y | Y | Y | - |
endpoints.manage | Remove, decommission and reactivate endpoints; deployment tokens; Add Computer; adoption requests; credential rotation | Y | Y | - | - | - |
endpoints.operate | Refresh a computer now; collect agent logs | Y | Y | Y | - | - |
blocklist.manage | Manage the blocklist; export the denylist | Y | Y | Y | - | - |
config.read | View platform configuration | Y | Y | Y | Y | Y |
config.write | Change configuration, including secrets; save the Prompt Protection policy; classifications; blocklist feed token | Y | Y | - | - | - |
ai_providers.read | View AI provider records | Y | Y | - | Y | Y |
ai_providers.write | Add or edit AI provider records and keys | Y | Y | - | - | Y |
prompt_templates.manage | Manage prompt templates | Y | Y | - | - | Y |
audit.read | View and export the audit log | Y | Y | - | Y | - |
license.manage | View and change license information: activate, import, redeem a code, confirm a moved server | Y | - | - | - | - |
reports.read | Generate and view your own reports | Y | Y | Y | Y | Y |
reports.manage | See, download and delete reports other people made | Y | Y | - | - | - |
debug.access | Debug / Reset, System Logs, system status, data reset | Y | Y | - | - | - |
tools.manage | Delete and merge AI tools; manage the AI Tool Catalog | Y | Y | - | - | - |
dlp.view_raw_content | View decrypted original prompt samples (every view is audited) | Y | Y | - | - | - |
response.read | Request and view enforcement (response) actions | Y | Y | Y | - | - |
response.enforce | Approve, reject, run, recall, roll back, disable, archive, delete actions | Y | Y | - | - | - |
ams.read | View the AMS agent registry, governance records and risk | Y | Y | Y | Y | - |
ams.manage | Edit AMS governance (owner, purpose, approval, pause); refer agents to AIDR | Y | Y | - | - | - |
ams.message | Send messages to AI agent sessions | Y | Y | - | - | - |
ams.approve | Approve or deny one pending AI agent tool call | Y | Y | - | - | - |
ams.policy | Change the AMS control policy and connectors | Y | Y | - | - | - |
ams.stop | Stop, hold, release, pause, resume and cancel AI agent work | Y | Y | - | - | - |
ams.bulk | Act on several AI agents at once (each act also needs its own permission) | Y | Y | - | - | - |
deployment.read | View deployment campaigns | Y | Y | Y | Y | - |
deployment.manage | Create or change campaigns; mint bootstrap credentials | Y | Y | - | - | - |
metrics.scrape_mint | Mint, rotate and revoke credentials for the unattended metrics feed | Y | Y | - | - | - |
artifact.read | View Artifact Analysis results and provider status | Y | Y | Y | Y | - |
artifact.analyze | Start, authorize and cancel an artifact analysis | Y | Y | Y | - | - |
artifact.manage | Delete artifact history; test providers; read or change Artifact Analysis settings | Y | Y | - | - | - |
In plain words
- Admin (
administrator) holds every permission exceptlicense.manage. - Analyst (
security_analyst) triages: it reads and changes alerts, policies, the blocklist and incidents, can refresh a computer and collect its logs, can request (but never approve or run) an enforcement action, can run artifact analyses and read reports. It cannot change configuration, manage users, remove endpoints, view the audit log, see original prompt samples or act on AI agents beyond reading them. - View Only (
read_only) reads: policies, alerts, endpoints, configuration values, AI provider records, reports, the audit log, AMS, deployment campaigns and artifact results. It changes nothing. - Developer holds no security-data permissions (no alerts, endpoints, policies or AMS). It reads configuration and reports and manages AI provider records and prompt templates.
What needs only a signed-in account
Some pages and routes check that you are signed in but do not check any permission. Any signed-in user, of any role (including View Only and Developer), can read these.
Plain statement: any signed-in user can read endpoint identity and raw telemetry. That means the list of endpoints (host name, user, IP address, operating system, agent version, risk), one endpoint's detail, and its raw telemetry rows (processes, network connections, browser AI visits, extensions, software, local AI, DNS names, AI agent signals), up to 1000 rows per request. Treat every account, including View Only, as having that access. Create accounts accordingly.
Routes that need only a signed-in account:
| Area | Routes (/api/v1/...) |
|---|---|
| Endpoints | GET /endpoints, GET /endpoints/{id}, GET /endpoints/{id}/telemetry, GET /endpoints/{id}/extension-changes, GET /extension-changes |
| AI tools and catalog | GET /tools, GET /tools/{id}/usage, GET /tool-catalog, GET /tool-catalog/freshness, GET /tool-catalog/{id} |
| Classification, policy, blocklist | GET /classifications, GET /classifications/{id}, GET /policies, GET /blocklist |
| Dashboards | GET /dashboard/stats, GET /topology, GET /reports/summary, GET /reports/executive, GET /behavior/summary, GET /network/summary, GET /network/provider-ip-ranges |
| Incidents | GET /incidents, GET /incidents/{id} |
| License | GET /license, GET /license/capacity, GET /license/activation |
| Notifications | GET /notifications/status |
| Roles | GET /rbac/roles, GET /rbac/permissions, GET /rbac/users/{id}/permissions, GET /rbac/users/{id}/roles |
| Your own account | POST /auth/logout, GET /auth/me, POST /auth/change-password, GET /auth/mfa/status, POST /auth/mfa/disable, POST /auth/mfa/recovery-codes/regenerate |
Everything else in the console routes needs a named permission (above). The agent and extension routes (register, check-in, configuration, gateway, extension download) are not for people: they use a deployment token, an endpoint credential or a gateway credential instead of an account. A few routes need nothing (the health and version routes, sign-in and setup).
Multifactor authentication (MFA)
- What it is: a second sign-in step with a 6-digit code from an authenticator app (time-based one-time password), or a one-time recovery code.
- Who must use it: the roles listed in the setting Require multi-factor sign-in for (Configuration, Security & Access). The default is Admin. The console offers Admin and Analyst; View Only can never be required, whatever the setting says. A user in a required role who has not enrolled is sent straight to enrolment at sign-in, including the first account at the end of first-run setup. Console role is what counts:
admincovers bothsuper_adminandadministrator. - Everyone else: any user may enrol or disable MFA for their own account from the account menu (Authentication / MFA, Recovery Codes). Turning it off needs a current code. Regenerating recovery codes needs a current code and replaces the old set.
- Recovery codes: 10 codes of 10 characters, shown once, each works once. A new set replaces the old.
- Time limit: the step between password and code (and forced enrolment) lasts 2 minutes. If it ends the console says: "This sign-in step has ended. It lasts 2 minutes, and a newer sign-in or a restart of YuviRed also ends it. Sign in again."
- Wrong codes: a wrong code counts as a failed sign-in on the same budget as a wrong password. In addition, more than 20 wrong or repeated code attempts for one account in an hour trigger a back-off with the message
Too many failed codes for this account. Retry in Ns.(HTTP 429). It slows guessing; it does not lock the account for good. - Lost phone and no recovery codes: an administrator with
users.manageturns that user's MFA off (the shield icon on Team / Users); the user enrols again at next sign-in. - Single sign-on: SSO users skip the server's own code step. By default the identity provider must prove it performed MFA for roles that require it (setting Require provider MFA for roles that require MFA, default On). Turning that off lets SSO sign-ins bypass the requirement.
Passwords
- At least 12 and at most 72 bytes; at least 3 of 4 character classes (lowercase, uppercase, digit, symbol); at least 6 different characters; must not contain the user's own name or email name, or a commonly guessed word (including leet-speak forms such as
P@ssw0rd); must not equal the current password or any of the last N (setting Prevent password reuse, default 5, range 0 to 24). Existing passwords are never re-checked. - The same rules apply at first-run setup, Add User, Reset Password and Change Password.
- No scheduled expiry. A password change is forced only when an administrator sets it (reset with a required change, or require password change). Until the user changes it, every call except changing the password is refused with HTTP 403
password_change_required. - A password an administrator issues as temporary stops working 72 hours after it was set. The sign-in is then refused exactly like a wrong password ("Invalid credentials"), and counts as a failed attempt.
Sign-in lockouts
| Rule | Value | What the user sees |
|---|---|---|
| Per source address and account | 8 failed attempts inside a rolling 5 minutes blocks that pair until the window drains. | HTTP 429 Too many failed login attempts. Please wait and try again. |
| Per account from any address | 30 failed attempts inside a rolling hour. A time-based cool-down, never a permanent lock. A successful sign-in does not clear it. A sign-in from the server computer itself (loopback) is exempt, so someone at the server can always sign in. | Same 429 message. |
| Wrong password and unknown user | Same answer for both. | HTTP 401 Invalid credentials |
| Audit | Failed sign-ins are audited, capped at 120 rows a minute per source address. |
On YuviRed Lite there is no Redis, so these counters live in the service's memory. A restart of the YuviRed service clears them. Because the per-account ceiling counts failures from every address, a person on the network who keeps failing can hold an account out of network sign-in for up to an hour; sign in at the server itself to get around it.
Sessions
- Length: a sign-in issues a token valid for 480 minutes (8 hours). After that the console shows the dialog Session Expired ("Your session has ended and background updates have been paused. Log in again to resume monitoring.") with Log In Again.
- Ended early by: Sign Out, a password change (your other sessions end), an administrator's reset, deactivating or deleting the user, and an administrator's revoke-sessions.
- Lite limit: Lite has no Redis, so the list of ended sessions is kept in memory. A restart of the YuviRed service forgets sign-outs, session endings after a password change and revoke-sessions: such a session works again until its own 8 hours run out. Deactivating or deleting a user still ends their sessions after a restart, and a required password change survives a restart.
- Active Sessions in the account menu is disabled: this build does not list individual sessions.
- A session also stops working while the server is locked for licensing (HTTP 402; see statuses-and-errors.md). Signing in, the account routes (your own password and MFA), the license screen, first-run setup and rolling back a response action (so a browser block applied earlier can still be lifted) keep working.
- Neither the session length nor the lockout numbers can be changed from the console.