> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/administration/roles-and-permissions.md).

# Roles & Permissions

## Quick answer

Create least-privilege ContextQA roles, configure permissions by resource, and assign roles to workspace users. Use this page to understand when the capability applies, complete its user-facing workflow, and verify the expected result.

## What this page covers

{% hint style="info" %}
**Who is this for?** Organization administrators and engineering managers responsible for user access, separation of duties, and audit readiness.
{% endhint %}

ContextQA manages workspace access from **Settings → User Management → Roles & Permissions**. A role combines a name and description with explicit permissions for users, workspaces, tests, roles, plugins, and the system audit log.

![ContextQA Create Role dialog showing role metadata, the default-role option, and resource-based permission groups](/files/TnKbuSQFfTDL6xthmYAX)

## Open the role manager

1. Open **Settings → User Management** (`/settings/user-managemant`).
2. Select the **Roles & Permissions** tab.
3. Search for an existing role or select **Create Role**.

The role list can be empty in a newly configured workspace. When no role exists, the user invitation dialog displays **No roles available**. Create the required role before assigning it to an invited user.

## Role fields

| Field                   | Current behavior                                      | Guidance                                                                            |
| ----------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Role Name**           | Required; the dialog displays a 20-character counter  | Use a responsibility-based name such as `QA Reviewer`, not a person's name          |
| **Description**         | Required; the dialog displays a 100-character counter | State what the role is allowed to accomplish and who owns it                        |
| **Set as default role** | Optional checkbox                                     | Enable only after reviewing every permission; new assignments may inherit this role |

## Permission groups

The current role dialog presents the following resource groups:

| Group            | Available permissions                            |
| ---------------- | ------------------------------------------------ |
| **User**         | View, Create, Update, Delete                     |
| **Workspace**    | View, Create, Update, Delete                     |
| **Test**         | View, Create, Update, Delete, Permanently Delete |
| **Role**         | View, Create, Update, Delete                     |
| **Plugin**       | Update                                           |
| **System Audit** | View                                             |

Permission labels in the portal are the source of truth for the current workspace and deployment. If a capability is not present in the dialog, do not assume that a similarly named permission exists.

{% hint style="warning" %}
**Delete and Permanently Delete are separate controls.** Grant permanent deletion only to administrators who understand the retention and recovery impact.
{% endhint %}

## Create a role

1. Select **Create Role**.
2. Enter a required name and description.
3. Decide whether the role should be the workspace default.
4. Enable the minimum permissions required for the job.
5. Review sensitive combinations such as user deletion plus role administration, or test deletion plus permanent deletion.
6. Select **Save**.
7. Invite or edit a test user and verify that the permitted pages and actions match the intended responsibility.

Do not test a new role with the only organization administrator account. Keep a separate administrator session available until the new access policy is verified.

## Assign a role to a user

1. Return to the **Users** tab.
2. Select **Invite user** or open the **More actions** menu for an existing user.
3. Select the appropriate role.
4. Save the user change.
5. Confirm the change through the System Audits page when the action is recorded.

The user table displays name, email, assigned roles, verification state, administrator state, and an actions menu. Role availability depends on roles already configured in the workspace.

## Least-privilege patterns

| Responsibility                    | Typical starting point                                                                                |
| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Test author                       | View/Create/Update Test; exclude user, role, and plugin administration                                |
| Test runner or CI service account | View Test and only the execution access exposed by the deployment; avoid user and role administration |
| QA reviewer                       | View Test plus the minimum update permission required by the review workflow                          |
| Integration administrator         | Update Plugin plus the read access needed to verify the integration                                   |
| Access administrator              | User and Role permissions; grant test deletion only when operationally required                       |
| Auditor                           | View System Audit and other read permissions required by the review scope                             |

These are design patterns, not built-in roles. Create the exact permission combination required by your organization and verify it in the target workspace.

## Access-review checklist

* Review default-role permissions after every organization-wide access change.
* Remove permissions that are no longer required; do not only add new ones.
* Use dedicated service accounts for automation and keep their role narrower than a human administrator role.
* Review plugin-update access because configuration panels can contain external-system credentials.
* Review permanent-deletion access separately from ordinary test maintenance.
* Use the system audit trail to investigate role and access changes.

## Related pages

* [Team Management](/administration/team-management.md) — invite and manage workspace users
* [System Configuration](/administration/system-configuration.md) — organization-wide defaults and configuration safety
* [Authentication](/administration/sso-and-authentication.md) — login modes and API credential handling
* [Administration Overview](/administration/administration.md) — all administration surfaces

{% hint style="info" %}
**Need an access-control walkthrough?** [Book an Enterprise Demo →](https://contextqa.com/book-a-demo/)
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://learning.contextqa.com/administration/roles-and-permissions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.