# Roles & Permissions

{% hint style="info" %}
**Who is this for?** Engineering Managers, IT Administrators, and VPs of Engineering configuring team access, authentication, and enterprise security controls.
{% endhint %}

ContextQA uses role-based access control (RBAC) to ensure that every team member has the appropriate level of access for their responsibilities — no more, no less. This page documents the built-in roles, their permissions, how to create custom roles, and how to assign roles to users.

***

## Default Roles

ContextQA ships with four built-in roles that cover the most common team structures. These roles cannot be deleted, but you can create additional custom roles alongside them.

| Role            | Description                                                                                  | Key Permissions                                            |
| --------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Admin**       | Full access to all features including user management, integrations, and all test operations | All permissions                                            |
| **QA Engineer** | Create, edit, and run tests; access results and AI features; cannot manage users or billing  | Test case CRUD, execution, results, AI tools, environments |
| **Developer**   | Run tests and view results without creating or modifying test cases                          | Execute tests, view reports, view test cases (read-only)   |
| **Viewer**      | Read-only access to everything                                                               | View test cases, view results, view dashboards             |

***

## Permission Matrix

The following table shows what each built-in role can do across all major feature areas.

| Permission                                 | Admin | QA Engineer | Developer | Viewer |
| ------------------------------------------ | ----- | ----------- | --------- | ------ |
| View test cases                            | Yes   | Yes         | Yes       | Yes    |
| View execution results                     | Yes   | Yes         | Yes       | Yes    |
| View dashboards and reports                | Yes   | Yes         | Yes       | Yes    |
| Create test cases                          | Yes   | Yes         | No        | No     |
| Edit test case steps                       | Yes   | Yes         | No        | No     |
| Delete test cases                          | Yes   | Yes         | No        | No     |
| Execute test cases                         | Yes   | Yes         | Yes       | No     |
| Execute test suites                        | Yes   | Yes         | Yes       | No     |
| Execute test plans                         | Yes   | Yes         | Yes       | No     |
| Create and edit test plans                 | Yes   | Yes         | No        | No     |
| Manage environments                        | Yes   | Yes         | No        | No     |
| Manage test data profiles                  | Yes   | Yes         | No        | No     |
| Access Knowledge Base                      | Yes   | Yes         | No        | No     |
| Manage custom agents                       | Yes   | Yes         | No        | No     |
| Create and approve healings                | Yes   | Yes         | No        | No     |
| Configure integrations (Jira, Slack, etc.) | Yes   | No          | No        | No     |
| Invite users                               | Yes   | No          | No        | No     |
| Edit user roles                            | Yes   | No          | No        | No     |
| Suspend or remove users                    | Yes   | No          | No        | No     |
| View system audit log                      | Yes   | No          | No        | No     |
| Create custom roles                        | Yes   | No          | No        | No     |
| Manage workspace settings                  | Yes   | No          | No        | No     |

***

## Creating Custom Roles

If the built-in roles do not match your team structure, you can create custom roles with a specific combination of permissions.

**Steps to create a custom role:**

1. Navigate to **Admin Settings → Roles and Permissions**
2. Click **Create Role**
3. Enter a role name (e.g., "Release Manager") and an optional description
4. Configure permissions by category. The permission categories are:

**User Access Permissions:**

* Create User
* Edit User
* Delete User
* View User List

**Workspace Access Permissions:**

* Create Workspace
* Edit Workspace Settings
* Delete Workspace
* View Workspace

**Test Operations Permissions:**

* Create Test Case
* Edit Test Case
* Delete Test Case
* Execute Test Case
* Execute Test Suite
* Execute Test Plan
* View Test Results
* Manage Test Data Profiles
* Manage Environments

**AI Features Permissions:**

* Access Knowledge Base
* Create Knowledge Base
* Manage Custom Agents
* View AI Insights
* Approve Auto-Healing

**Administration Permissions:**

* Configure Integrations
* View Audit Log
* Create Role
* Edit Role
* Assign Role to User

5. Click **Save Role**

The new role immediately appears in the role dropdown when inviting or editing users.

***

## Assigning Roles to Users

### When Inviting a New User

1. Navigate to **Admin Settings → User Management**
2. Click **+ Invite User**
3. Enter the user's email address
4. Select the role from the **Role** dropdown
5. Click **Send Invitation**

The user receives an email invitation. After they accept and set their password, their permissions are determined by the assigned role.

### Changing an Existing User's Role

1. Navigate to **Admin Settings → User Management**
2. Find the user in the list
3. Click **Edit** (pencil icon) next to the user's name
4. Change the role in the **Role** dropdown
5. Click **Save**

Role changes take effect immediately — the user's next page load reflects the new permissions. There is no need to notify the user or ask them to log out.

***

## Inviting Users

User invitations are sent by email and expire after 7 days if not accepted.

**To invite a user:**

1. Navigate to **Admin Settings → User Management**
2. Click **Invite User**
3. Enter the email address
4. Select the role
5. Click **Send Invitation**

**If an invitation expires:**

* The user will see an error if they click the expired link
* Find the user in the User Management list (they will appear as "Invited - Expired")
* Click **Resend Invitation** to send a new link

**For multiple users:** Send one invitation per user. Invitations are sent individually.

***

## User States

Each user in the system has one of the following states:

| State         | Description                                                                                        |
| ------------- | -------------------------------------------------------------------------------------------------- |
| **Active**    | User has accepted the invitation and can log in                                                    |
| **Invited**   | Invitation sent but not yet accepted                                                               |
| **Suspended** | Account disabled by an admin — user cannot log in. Execution history and test cases are preserved. |
| **Removed**   | User removed from workspace — test cases they created remain in the workspace                      |

To suspend a user (e.g., when an employee leaves):

1. **Admin Settings → User Management**
2. Find the user
3. Click **Suspend**

To reactivate a suspended user:

1. **Admin Settings → User Management**
2. Find the suspended user (filter by "Suspended" status)
3. Click **Reactivate**

***

## Workspace-Level Access Isolation

All roles in ContextQA are scoped to a workspace. A user's role in Workspace A does not affect their access in Workspace B. Users must be invited to each workspace separately.

This means you can give a contractor QA Engineer access to one workspace without granting them any access to other workspaces your organization maintains.

To completely isolate access between projects, create separate workspaces and invite only the relevant team members to each one.

***

## Service Accounts for CI/CD

When connecting CI/CD pipelines or the MCP server to ContextQA, best practice is to create a dedicated service account:

1. Create a new ContextQA account with an email like `ci-service@yourcompany.com`
2. Invite it to the workspace with the **QA Engineer** role (sufficient for executing tests and reading results)
3. Use this account's credentials (`CONTEXTQA_USERNAME` and `CONTEXTQA_PASSWORD`) in your CI secrets
4. Do not use your personal admin account for automation

This approach lets you revoke CI access independently (by suspending the service account) without affecting your personal login, and keeps the audit log clean — all automated actions appear under the service account name.

***

## Feature Access Gating

Some features require a subscription tier in addition to an appropriate role:

| Feature                   | Subscription Requirement      |
| ------------------------- | ----------------------------- |
| Knowledge Base            | Plan with AI features enabled |
| Custom Agents             | Plan with AI features enabled |
| Workspace Switcher        | Multi-workspace plan          |
| UI Elements discovery     | Plan with Elements access     |
| Execution results history | Plan with Results access      |

If a feature shows a lock icon or an upgrade prompt, the restriction is at the subscription level, not the role level. Contact your workspace owner or the ContextQA support team to discuss plan options.

***

## Audit Log

The system audit log records every significant action taken in the workspace. Admins can access it at **Admin Settings → System Audits**.

The audit log captures:

* Who performed the action (user email)
* What action was taken (created test case, executed test plan, changed user role, etc.)
* When it occurred (timestamp)
* From which IP address

The audit log is read-only — entries cannot be modified or deleted. Use it for compliance reviews, security investigations, or troubleshooting access issues.

## Related Pages

* [Team Management](https://learning.contextqa.com/administration/team-management) — invite users and manage team membership
* [SSO & Authentication](https://learning.contextqa.com/administration/sso-and-authentication) — configure single sign-on providers
* [Administration Overview](https://learning.contextqa.com/administration/administration) — all administration settings

{% hint style="info" %}
**Enterprise-ready: SSO, RBAC, and centralized access management.** [**Book an Enterprise Demo →**](https://contextqa.com/book-a-demo/) — Get a walkthrough of enterprise controls, SSO setup, and compliance features for your organization.
{% endhint %}