Roles & Permissions (RBAC)

Controlinfra uses Role-Based Access Control (RBAC) to manage what users can do within an organization. Every member is assigned a role (built-in or custom), and every role maps to a set of permissions. The server checks permissions, not role names, so custom roles can grant exactly the access you need.

Built-in Roles

Role	Description
Owner	Full access. Can manage billing, delete the org, and transfer ownership. Only one owner per org.
Admin	Full access to everything except billing and org deletion.
Member	Can work with repos, scans, drifts, discovery, and widgets. Cannot change integrations, runners, guardrails, or org settings.
Viewer	Read-only across all features.

Permission Matrix

Action	Owner	Admin	Member	Viewer
View repos, scans, drifts, discovery	Yes	Yes	Yes	Yes
Create/edit repos, trigger scans	Yes	Yes	Yes	No
Manage drifts (fix, revert, PR)	Yes	Yes	Yes	No
Run cloud discovery	Yes	Yes	Yes	No
Create/manage widgets	Yes	Yes	Yes	No
Export CSV	Yes	Yes	Yes	No
Manage integrations (AWS, Azure, GCP, Slack, Jira, CLI tokens)	Yes	Yes	No	No
Manage runners	Yes	Yes	No	No
Create/deploy guardrails	Yes	Yes	No	No
Create/manage drift watches	Yes	Yes	No	No
View audit logs	Yes	Yes	No	No
Manage members & invitations	Yes	Yes	No	No
Manage org settings	Yes	Yes	No	No
Manage billing	Yes	No	No	No
Delete organization	Yes	No	No	No

Custom Roles Team+

Teams on the Team plan or higher can create custom roles with granular permissions. Custom roles let you define exactly what a user can do without being limited to the four built-in roles.

Custom roles can be used to either restrict a role (e.g., an admin who can't touch billing) or elevate a member-level user (e.g., a member who can manage runners). Permission checks on the server are authoritative — custom-role permissions grant real access to previously admin-only actions.

Available Permissions

Custom roles can include any combination of these 22 permissions:

Category	Permissions
Repositories	repos:read, repos:write
Scans	scans:read, scans:write
Drifts	drifts:read, drifts:write
Cloud Discovery	discovery:read, discovery:write
Drift Watch	drift-watch:read, drift-watch:write
Guardrails	guardrails:read, guardrails:write
Runners	runners:read, runners:write
Integrations	integrations:read, integrations:write
Widgets & Export	widgets:read, widgets:write, export:csv
Organization	org:read, org:members, org:admin

A member assigned a custom role must still be at least member-level in the built-in role hierarchy. owner is reserved for a single user per org; custom roles cannot grant billing or org-deletion access (those remain owner-only).

Creating a Custom Role

1. Go to Organizations and select your org.
2. Click the Roles tab (visible to admins on Team+ plans).
3. Click Create Role.
4. Enter a name, description, and color.
5. Select the permissions for this role.
6. Click Create Role to save.

Up to 10 custom roles per organization.

Assigning a Custom Role

Once created, custom roles appear in the role dropdown when editing a member's role:

1. Go to the Members tab.
2. Click the role badge next to a member's name.
3. Select the custom role from the dropdown.

Deleting a Custom Role

A custom role can be deleted only when no members are assigned to it. Reassign any members first.

Audit Trail

All role-related actions are recorded in the org's audit log:

• org.role_created, org.role_updated, org.role_deleted
• org.member_role_changed

Each entry includes the actor, target, and full permission set at time of change. Accessible via Settings → Audit Log (admin-only) or the API.

API Reference

Custom roles can also be managed via the API:

# List built-in and custom roles
GET /api/orgs/:orgId/roles

# Get a single custom role
GET /api/orgs/:orgId/roles/:roleId

# Create a custom role
POST /api/orgs/:orgId/roles
{
  "name": "Security Reviewer",
  "description": "Can view guardrails and audit logs",
  "permissions": ["guardrails:read", "drifts:read", "org:read"],
  "color": "#6366f1"
}

# Update a custom role
PUT /api/orgs/:orgId/roles/:roleId

# Delete a custom role (must have no assigned members)
DELETE /api/orgs/:orgId/roles/:roleId

All custom-role endpoints require the Team plan or higher and the org:admin permission. See the Organizations API reference for full details.