> For the complete documentation index, see [llms.txt](https://docs.interlynk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interlynk.io/administration/role-management.md).

# Role Management

Interlynk uses role-based access control (RBAC) to govern what users and service tokens can do within an organization. Three system roles are provided by default, and administrators can create custom roles with granular permissions.

***

## Default Roles

Interlynk ships with three system roles that cannot be modified or deleted:

| Role         | Description                                                                                                      |
| ------------ | ---------------------------------------------------------------------------------------------------------------- |
| **Admin**    | Full access to all features and settings. Can manage users, roles, integrations, and organization configuration. |
| **Operator** | Can manage products, SBOMs, policies, integrations, and users. Cannot delete the organization or modify billing. |
| **Viewer**   | Read-only access to products, SBOMs, vulnerabilities, policies, and user lists. Cannot make changes.             |

{% hint style="warning" %}
Permissions associated with default roles Admin, Operator, and Viewer are read-only and cannot be modified.
{% endhint %}

### Permission Matrix

The table below lists all permissions and their assignment across default roles.

| Permission                                    | Admin | Operator | Viewer |
| --------------------------------------------- | :---: | :------: | :----: |
| **Organization**                              |       |          |        |
| View organization                             |   ✓   |     ✓    |    ✓   |
| Update organization                           |   ✓   |     —    |    —   |
| Delete organization                           |   ✓   |     —    |    —   |
| **Products**                                  |       |          |        |
| View products                                 |   ✓   |     ✓    |    ✓   |
| Create products                               |   ✓   |     ✓    |    —   |
| Update products                               |   ✓   |     ✓    |    —   |
| Delete products                               |   ✓   |     ✓    |    —   |
| Edit share link                               |   ✓   |     ✓    |    —   |
| Edit product automations                      |   ✓   |     ✓    |    —   |
| Edit product policies                         |   ✓   |     ✓    |    —   |
| Edit product integrations                     |   ✓   |     ✓    |    —   |
| Edit product settings                         |   ✓   |     ✓    |    —   |
| **SBOMs**                                     |       |          |        |
| View SBOMs                                    |   ✓   |     ✓    |    ✓   |
| Update SBOMs                                  |   ✓   |     ✓    |    —   |
| Delete SBOMs                                  |   ✓   |     ✓    |    —   |
| Edit SBOM components                          |   ✓   |     ✓    |    —   |
| Edit vulnerabilities                          |   ✓   |     ✓    |    —   |
| Edit checks                                   |   ✓   |     ✓    |    —   |
| Sign SBOMs                                    |   ✓   |     ✓    |    —   |
| Reprocess SBOMs                               |   ✓   |     ✓    |    —   |
| **Users**                                     |       |          |        |
| View users                                    |   ✓   |     ✓    |    ✓   |
| Invite users                                  |   ✓   |     ✓    |    —   |
| Edit user roles                               |   ✓   |     ✓    |    —   |
| Edit teams                                    |   ✓   |     ✓    |    —   |
| Delete users                                  |   ✓   |     ✓    |    —   |
| **Vulnerabilities**                           |       |          |        |
| View vulnerabilities (`view_vulnerabilities`) |   ✓   |     ✓    |    ✓   |
| View feeds                                    |   ✓   |     ✓    |    ✓   |
| Manage feeds                                  |   ✓   |     ✓    |    —   |
| Manage lists                                  |   ✓   |     ✓    |    —   |
| Manage custom fields                          |   ✓   |     ✓    |    —   |
| **Licenses**                                  |       |          |        |
| View licenses                                 |   ✓   |     ✓    |    ✓   |
| Edit licenses                                 |   ✓   |     ✓    |    —   |
| **Policies**                                  |       |          |        |
| View policies                                 |   ✓   |     ✓    |    ✓   |
| Edit policies                                 |   ✓   |     ✓    |    —   |
| Run policy scans                              |   ✓   |     ✓    |    —   |
| Delete policies                               |   ✓   |     ✓    |    —   |
| **Support**                                   |       |          |        |
| View support                                  |   ✓   |     ✓    |    ✓   |
| Edit support                                  |   ✓   |     ✓    |    —   |
| Delete support                                |   ✓   |     ✓    |    —   |
| View support levels                           |   ✓   |     ✓    |    ✓   |
| Edit support levels                           |   ✓   |     ✓    |    —   |
| Delete support levels                         |   ✓   |     ✓    |    —   |
| **Vendor Management**                         |       |          |        |
| View requests                                 |   ✓   |     ✓    |    ✓   |
| Edit requests                                 |   ✓   |     ✓    |    —   |
| **Connections**                               |       |          |        |
| View connections                              |   ✓   |     ✓    |    ✓   |
| Edit connections                              |   ✓   |     ✓    |    —   |
| Delete connections                            |   ✓   |     ✓    |    —   |
| **Notifications**                             |       |          |        |
| View notification settings                    |   ✓   |     ✓    |    ✓   |
| Edit notification settings                    |   ✓   |     ✓    |    —   |
| **API Tokens**                                |       |          |        |
| View API tokens                               |   ✓   |     ✓    |    ✓   |
| Manage API tokens (`manage_api_tokens`)       |   ✓   |     ✓    |    —   |

{% hint style="warning" %}
`view_vulnerabilities` gates vulnerability and VEX exports, download options, and the Copy VEX action. Unlike other view permissions, it is **not** granted automatically to every role. The built-in Admin, Operator, and Viewer roles include it, but a custom role must list it explicitly or those users will see vulnerability data on screen with the export and download actions hidden.
{% endhint %}

{% hint style="info" %}
`manage_api_tokens` is a dedicated permission decoupled from `update_organization`. This means Operator and Developer roles can create and manage API tokens — including service tokens — without requiring full organization settings access. Assign this permission to CI/CD roles that need to rotate tokens but should not have access to org-level configuration.

A non-admin with `manage_api_tokens` can give a service token only a role whose permissions they hold themselves, and never Admin. Existing service tokens created by non-admins were aligned to their creator's role in v4.0.4.
{% endhint %}

### Use Cases for Default Roles

| Role         | Typical User                                             |
| ------------ | -------------------------------------------------------- |
| **Admin**    | Security team leads, platform owners, DevOps managers    |
| **Operator** | AppSec engineers, DevOps engineers, release managers     |
| **Viewer**   | Developers, compliance auditors, management stakeholders |

**Viewer capabilities note:** Viewers can access SBOM relationships, component relationship actions, and support level data in read-only mode. They can also view feeds, internal components, and custom vulnerabilities, download VEX, pin products, and edit their personal notification preferences, including the address rows in personal Slack, Teams, and Email configuration. They cannot modify SBOMs, policies, vulnerabilities, or organization settings.

***

## Custom Roles

Custom roles allow you to define granular permission sets beyond the three defaults. Use custom roles to implement least-privilege access patterns.

### Creating Custom Roles

1. Navigate to **Settings > Organization > People & access > Roles**.
2. Click **Create Role**.
3. Enter a **Name** for the role (minimum 4 characters). Use a descriptive name like `AppSec Reviewer` or `CI Upload Agent`.
4. Select **Copy Permission From** to start with an existing role's permissions as a baseline.
5. Click **Create**.

The new role is created with the copied permission set. You can then adjust individual permissions as needed. A permission can only be enabled together with its parent permission.

When inviting users, the role picker offers only the roles you are allowed to assign.

{% hint style="info" %}
Role names must be unique within the organization (case-insensitive).
{% endhint %}

### Deleting Custom Roles

1. Navigate to **Settings > Organization > People & access > Roles**.
2. Click the action menu on the role's row.
3. Select **Delete**.
4. Choose the role that the deleted role's users should move to.
5. Confirm. Interlynk moves every user to the new role first, then deletes the role.

**Delete** stays disabled until the role's user list has loaded, so users are never left without a role.

{% hint style="warning" %}
Only users are moved. Reassign any service tokens that use the role before deleting it.
{% endhint %}

### Granular Permission Selection

Permissions are organized into categories. When creating or editing a custom role, select only the permissions required for the role's purpose. Refer to the permission matrix above for available permissions.

### Recommended Patterns

| Custom Role           | Permissions                                                                                                                       | Use Case                                                                        |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **AppSec Reviewer**   | View organization, View products, View SBOMs, View policies, View vulnerabilities, Edit vulnerabilities, View feeds, Manage feeds | Security analyst who triages vulnerabilities but does not manage infrastructure |
| **Compliance Viewer** | View organization, View products, View SBOMs, View policies, View licenses, View vulnerabilities, View feeds                      | Auditor or compliance officer with read-only access                             |
| **CI Upload Agent**   | View products, Create products, Update SBOMs, View API tokens, Manage API tokens                                                  | Service token role for CI/CD pipelines that only upload SBOMs                   |
| **Policy Manager**    | View organization, View products, View SBOMs, View policies, Edit policies, Run policy scans, Delete policies                     | User responsible for defining and maintaining security policies                 |
| **Integration Admin** | View organization, View connections, Edit connections, Delete connections, View notification settings, Edit notification settings | User responsible for managing integrations and notifications                    |

### Bulk Role Assignment

To assign a role to multiple users at once, use the **Bulk Apply** feature:

1. Navigate to **Settings > Organization > People & access > Roles**.
2. Select a role.
3. Use the bulk apply action to assign the role to selected users.

***

## Common Misconfigurations

| Issue                                           | Symptom                                                      | Fix                                                                                    |
| ----------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| Custom role missing critical permission         | User cannot perform expected action                          | Review the permission matrix and add the missing permission                            |
| Custom role missing `view_vulnerabilities`      | Vulnerability and VEX export and download actions are hidden | Add View Vulnerabilities to the role; it is not granted automatically                  |
| Service token assigned Admin role               | Excessive permissions for automation                         | Create a minimal custom role and reassign the token                                    |
| All users assigned Admin                        | No effective access control                                  | Implement role separation — most users should be Operators or Viewers                  |
| Custom role deleted while service tokens use it | Service tokens are not moved to the new role                 | Reassign service tokens to another role before deleting; users are moved automatically |
| Role name too short                             | Creation fails with validation error                         | Use at least 4 characters for role names                                               |

***

## Recommended Best Practices

* Start with the **Viewer** role and add permissions incrementally — it is easier to grant access than to revoke it.
* Create **dedicated service token roles** with only the permissions CI/CD pipelines need (e.g., SBOM upload and product view).
* Review role assignments **quarterly** as part of your security hygiene.
* Use **descriptive role names** that communicate purpose (e.g., `Release Engineer` rather than `Custom Role 1`).
* Document your custom roles and their intended use cases in your team's runbook.
* Avoid creating too many custom roles — consolidate where possible to reduce management overhead.
