Admin Privileges
Granular admin privileges are available on every data plane running dp_branch_048 or later. See Upgrading before you roll this out.
Until now, deciding what an administrator could change was close to all-or-nothing. A viewer could read everything and edit nothing, and anyone above viewer could edit everything. There was no way to say "Dana may edit our policies, but must not touch connectors, and must never delete anything."
Admin Privileges closes that gap. You define a named role that carries an access level for each configuration area, then assign it to an administrator.
The three access levels
Each configuration area is set to one of four values:
| Level | What it allows |
|---|---|
| No access | The area is off limits entirely. |
| Read only | View the area. No creating, editing, or deleting. |
| Read-write | View, create, and edit. Cannot delete. |
| Full access | Everything, including delete. |
The levels are cumulative, so read-write includes everything read only allows.
Delete is deliberately separated from edit. Full access is reserved for destroying a thing outright: removing an agent role, a DLP pattern, a SIEM destination, an inbound rule, or deprovisioning an agent. That means you can hand someone day-to-day editing rights without also handing them the ability to erase your configuration.
Operations that change a resource without destroying it stay at read-write. Revoking a role from an agent is one example: it sits at read-write alongside assigning one, because it would be strange to let someone add a role but not take it back.
What you can govern
| Area | Covers |
|---|---|
| Agent roles | The RBAC roles assigned to agents at enrollment. |
| Policies | Policies, policy change requests, and inbound rules. |
| DLP | DLP patterns and prompt-firewall settings. |
| SIEM | SIEM destinations and delivery testing. |
| Agents | Agent enrollment, suspension, quarantine, credential rotation, and deprovisioning. |
| Admin users | Inviting, editing, and deactivating dashboard users. Restrict-only, see below. |
| Enrollment | Enrollment tokens. |
| Integrations | The integrations topology view. |
| Connectors | Reserved. See Current limitations. |
Inbound rules are governed by Policies rather than a separate area, because they are policy-layer rules.
The rule that surprises people
An administrator with no privilege role assigned keeps exactly the access they have today. Viewers stay read-only everywhere, and every other role, including analyst and policy author, keeps full access everywhere.
Assigning a role is what switches someone onto the matrix. Nothing changes for anyone the moment you upgrade, and nobody is signed out.
This is deliberate. Rolling out a permissions system that silently narrows people's access on a Tuesday morning is how you generate support tickets and lose trust in the tool. You opt each person in when you are ready.
Setting it up
Everything lives under Settings → Admin Privileges.
1. Create a role
Choose New role, give it a name that describes the job rather than the person, for example policy-editor or auditor, and set a level for each area in the grid. Anything you leave at No access grants nothing.
2. Assign it
In the Assignments table, click the role name next to an administrator to assign it, and click again to remove it. The change takes effect on their very next request. There is no need for them to sign out and back in.
3. Confirm what they will see
An administrator's effective access is available to the dashboard through GET /api/v1/admin/users/me/permissions, which the interface uses to hide controls the person cannot use. They will not be presented with buttons that only produce a permission error.
Built-in roles
Behavry ships four built-in roles that mirror the classic hierarchy: admin (full access everywhere), viewer and analyst (read only everywhere), and policy_author (read-write on policies and DLP, read elsewhere).
Built-in roles are shared by every tenant on the deployment, so they are read-only in the dashboard and show a lock. If one is close to what you want, create your own role and adjust it rather than editing the shared definition. Only a Behavry platform operator can change a built-in.
If someone has more than one role
Assign several roles and the most permissive level wins for each area independently. Someone holding a read-only role and a policy-editing role ends up read-write on policies and read only elsewhere. Roles add up, they never subtract.
Two safety rules
You cannot change your own privileges. Neither assigning nor removing a role on your own account is permitted. This blocks the obvious escalation path, granting yourself full access, and the equally obvious mistake, demoting yourself and locking your organisation out of its own user management. Ask another administrator to make the change.
A platform operator can always recover you. Behavry super-admins bypass the matrix entirely, so if your organisation does strand itself, support can restore access.
API
Roles: backend/behavry/admin/admin_roles_routes.py.
| Method | Path | Purpose |
|---|---|---|
GET | /api/v1/admin/roles/catalogue | The governed areas and access levels |
GET | /api/v1/admin/roles | Built-in roles plus your tenant's own |
POST | /api/v1/admin/roles | Create a role |
PATCH | /api/v1/admin/roles/{id} | Rename, re-describe, or change the matrix |
DELETE | /api/v1/admin/roles/{id} | Delete a role |
GET | /api/v1/admin/users/{id}/admin-roles | Roles assigned to a user |
POST | /api/v1/admin/users/{id}/admin-roles | Assign a role |
DELETE | /api/v1/admin/users/{id}/admin-roles/{role_id} | Remove a role |
GET | /api/v1/admin/users/me/permissions | Your own effective access |
A matrix is sent as {"policies": "read_write", "agent_roles": "read"}. An unrecognised area or level is rejected with a 422 rather than quietly ignored, so a typo cannot leave you with a role that appears to grant something but does not.
Managing privileges is itself governed by the Admin users area: read to look, read-write to create and edit roles, full access to delete a role or remove an assignment.
User management is restrict-only, by design
Admin users behaves differently from the other areas, on purpose. You can use the matrix to take user management away from someone, for example pinning a policy author to Read so they can see the team list but not invite or deactivate anyone. You cannot use it to give user management to someone whose base role is below admin. Managing users remains a tenant-administrator function.
This is a deliberate boundary, not a gap waiting to be closed.
User management is a meta-privilege: whoever holds it can reach full administration indirectly, by inviting a new admin, promoting an existing user, resetting an administrator's password and signing in as them, or authoring a role and assigning it. Each of those routes has to be closed individually, and closing them is exactly the kind of change where a small oversight becomes a privilege-escalation bug. Delegating user administration safely is a hard problem that deserves its own design, most likely with an approval step or a two-administrator rule, rather than being inferred from a permission grid.
So the product takes the conservative position: the eight configuration areas are freely delegable, and the one that governs people is not.
If you need a dedicated user administrator who is not otherwise a full admin, tell us. It is a reasonable enterprise requirement and worth building properly.
Current limitations
Connectors is reserved. The area appears in the grid but no routes are attached to it yet, so setting a level there currently has no effect. It is listed so the shape of the matrix does not change under you later.
Self-service is never blocked. Changing your own password and reading your own permissions are always available, whatever your matrix says. Locking someone out of their own password is not a permission model, it is an outage.
What changed for existing tenants
Access is unchanged for everyone on upgrade, with one intentional tightening: deleting a DLP pattern, a SIEM destination, or an inbound rule previously only required being signed in as any administrator, which included viewers. Those three now require full access on their area. Every role above viewer is unaffected.
Upgrading
This feature adds columns to the admin_roles table, so an upgrade must run its migrations. Data planes need alembic upgrade dp@head and control planes need alembic upgrade cp@head. A plane that receives the new image without running migrations will return errors from any screen that reads admin roles.
The standard dev deployment pipeline runs data-plane migrations automatically. Control-plane upgrades are the ones to watch.
Related
- User Roles & Invites — the base roles that privilege roles refine
- Administration — where the Admin Privileges tab lives
- Agent Roles — what enrolled agents may do, a separate system