> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codethreat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles and Permissions

> Understanding user roles and access control in CodeThreat

CodeThreat uses role-based access control (RBAC) to manage what team members can see and do.

## Built-In Roles

CodeThreat provides two built-in role templates:

<CardGroup cols={2}>
  <Card title="ADMIN" icon="user-shield">
    Full access to manage organization, repositories, and team
  </Card>

  <Card title="USER" icon="user">
    Standard member access with read permissions
  </Card>
</CardGroup>

<Note>
  Organizations can also create custom roles with specific permissions tailored to their needs.
</Note>

***

## ADMIN Role

### Capabilities

**Organization Management**:

* Manage organization settings
* Invite/remove members
* Assign roles
* Manage billing and subscription
* View audit logs

**Repository Management**:

* Connect VCS integrations
* Import/remove repositories
* Configure repository settings
* Set up automated scanning
* Configure AI features

**Security Findings**:

* View all violations
* Assign violations
* Suppress violations
* Run scans
* Generate reports

**Team Collaboration**:

* Comment on violations
* Create and share reports
* Configure notifications

### When to Use

* Organization owners
* Security team leads
* DevSecOps managers
* Anyone needing full administrative access

***

## USER Role

### Capabilities

**Security Findings**:

* View violations in accessible repositories
* View scan history and results
* View dashboards and reports
* Comment on violations

**Limitations**:

* Cannot manage organization settings
* Cannot invite/remove members
* Cannot manage billing
* Cannot connect VCS integrations
* Cannot trigger scans
* Cannot assign or suppress violations
* Cannot configure repository settings

### When to Use

* Software engineers (read-only access)
* Stakeholders
* Compliance/audit teams
* Product managers
* Anyone needing view-only access

***

## Permission Matrix

| Action                    | ADMIN | USER | Custom Roles |
| ------------------------- | ----- | ---- | ------------ |
| **Organization**          |       |      |              |
| Manage settings           | ✅     | ❌    | ❌            |
| Invite members            | ✅     | ❌    | ❌            |
| Manage billing            | ✅     | ❌    | ❌            |
| **Repositories**          |       |      |              |
| Connect VCS               | ✅     | ❌    | ❌            |
| Configure settings        | ✅     | ❌    | ❌            |
| View repositories         | ✅     | ✅    | ✅            |
| **Scanning**              |       |      |              |
| Trigger scans             | ✅     | ✅    | ❌            |
| View scan results         | ✅     | ✅    | ✅            |
| Configure automated scans | ✅     | ❌    | ❌            |
| **Violations**            |       |      |              |
| View violations           | ✅     | ✅    | ✅            |
| Assign violations         | ✅     | ✅    | ❌            |
| Suppress violations       | ✅     | ✅    | ❌            |
| Comment on violations     | ✅     | ✅    | ✅            |
| **Reporting**             |       |      |              |
| View reports              | ✅     | ✅    | ✅            |
| Generate reports          | ✅     | ✅    | ❌            |
| Share reports             | ✅     | ✅    | ❌            |

***

## Repository-Level Permissions

In addition to organization roles, control access to specific repositories.

### Grant Repository Access

<Steps>
  <Step title="Navigate to Repository Settings">
    Repository → **Settings** → **Access Control**
  </Step>

  <Step title="Add User or Team">
    Click **Add Member** or **Add Team**
  </Step>

  <Step title="Select User/Team">
    Choose from organization members or teams
  </Step>

  <Step title="Set Permission Level">
    Choose: Admin, Write, or Read
  </Step>

  <Step title="Save">
    Click **Grant Access**
  </Step>
</Steps>

### Repository Permission Levels

**Admin**: Manage repository settings, run scans, manage violations, configure automation

**Write**: Run scans, assign and suppress violations, comment on violations

**Read**: View violations, view scan results, view reports

<Note>
  Organization-level Admins have access to all repositories regardless of repository-level permissions.
</Note>

***

## Teams

Group users into teams for easier access management.

### Create a Team

<Steps>
  <Step title="Navigate to Teams">
    **Organization Settings** → **Teams**
  </Step>

  <Step title="Create Team">
    Click **Create Team**
  </Step>

  <Step title="Configure Team">
    Set name, description, and add members
  </Step>

  <Step title="Grant Repository Access">
    Assign team access to repositories
  </Step>
</Steps>

### Benefits of Teams

* Simplified access management
* Organized collaboration
* Notification routing
* Ownership clarity

***

## Changing Roles

<Steps>
  <Step title="Navigate to Members">
    **Organization Settings** → **Members**
  </Step>

  <Step title="Select User">
    Find user whose role you want to change
  </Step>

  <Step title="Change Role">
    Click role dropdown and select new role
  </Step>

  <Step title="Confirm">
    Confirm role change
  </Step>
</Steps>

<Warning>
  Role changes take effect immediately. Demoting an Admin means they lose access to organization settings instantly.
</Warning>

***

## Removing Team Members

<Steps>
  <Step title="Navigate to Members">
    **Organization Settings** → **Members**
  </Step>

  <Step title="Select User">
    Find user to remove
  </Step>

  <Step title="Remove">
    Click **Remove** button
  </Step>

  <Step title="Confirm">
    Confirm removal (cannot be undone)
  </Step>
</Steps>

**What happens**:

* User loses access immediately
* Violations assigned to them remain assigned (reassign if needed)
* Comments and activity history preserved
* User is notified via email

***

## Best Practices

* **Principle of least privilege**: Assign minimum required role
* **Use teams**: Group users for easier management
* **Repository-level permissions**: Restrict sensitive repository access
* **Regular access review**: Quarterly review of user access
* **Remove departing employees**: Remove access on last day
* **Document role decisions**: Note why users have specific roles

***

## Audit and Compliance

### Audit Logs

Track all permission-related actions:

* Role assignments and changes
* User invitations and removals
* Repository access grants/revokes
* Team membership changes

Access: **Organization Settings** → **Audit Logs**

### Compliance Requirements

For compliance (SOC 2, ISO 27001, etc.):

* Regular access reviews
* Principle of least privilege
* Audit log retention
* Timely access removal
* Documented RBAC policy

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Inviting Members" icon="user-plus" href="/team/inviting-members">
    Add team members
  </Card>

  <Card title="Repository Access" icon="folder-open" href="/team/repository-access">
    Control repository permissions
  </Card>
</CardGroup>