# Scopes for uip tm

> The OAuth scopes each uip tm command needs when you sign in with an external application, and ready-to-use --scope lists for CI.

When you sign in with an external application, every `uip tm` command needs the application to hold the right Test Manager (`TM.*`) scopes, and some commands also need Orchestrator (`OR.*`) scopes. This page lists them per command, with ready-to-use `--scope` lists.

## When scopes apply

| Sign-in | What Test Manager checks | What you do |
|---|---|---|
| User login (`uip login` in a browser) | Your project roles and tenant permissions. | No action. Scopes are not configured for a user login. |
| External application (`uip login --client-id … --client-secret …` or `--client-assertion …`, see [Authentication](./authentication.md)) | The application scopes in the access token. | The external application holds the scopes on this page, and the sign-in passes an explicit `--scope` list. |

An external application sign-in requires an explicit `--scope` list. Without it, Identity puts every scope the application holds into the token, and the sign-in fails once that list gets too long. Each scope in the list must be one the application was granted.

```bash
uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET \
  --scope "TM.Projects TM.TestSets TM.TestExecutions OR.Folders.Read OR.Execution.Read" \
  --tenant <TENANT_NAME>
```

The scopes the current token carries appear in `Data.Scopes` of the `uip login status --detailed --output json` output.

## How Test Manager evaluates scopes

- **Full, read, and write scopes.** `TM.TestCases` allows both reading and changing test cases. `TM.TestCases.Read` allows only `GET` requests, and `TM.TestCases.Write` allows only the others. Commands that filter or search data send a `POST` even when they only read data, so a `.Read`-only application can fail on them. The full scope covers every command; a narrower scope works only when it has been tested for every command in use.
- **Project resolution.** Every command that takes `--project-key`, `--project-id`, or `--test-set-key`, or that falls back to the tenant's default project, also needs `TM.Projects`.
- **Permission requirements.** A scope lets the token call the API. The application also needs the Test Manager project roles, and the Orchestrator folder roles, for the data it touches.

## Test Manager scopes by command

The base scope applies to every command in the row. The last column lists the extra scopes that specific commands or options need, or points to the conditional scopes table when a command group has several.

| Commands | Base scope | Extra scopes |
|---|---|---|
| `project` (`list`, `get-default`, `create`, `update`, `delete`, `export`, `import`, `set-default-folder`, `clear-default-folder`, `owners list`, `settings get`, `settings update`), `project-permissions get`, `migration get`, `migration list`, `migration download`, `export-jobs get` | `TM.Projects` | `project update --set-default`: `TM.Administration` |
| `migration schemas list`, `migration schemas download` | `TM.Users` (or `TM.Users.Read`) | — |
| `testcases` (create, list, get, update, delete, `clone`, `export`, `steps`, `parameters`, `list-*`, `group-by`, `bulk-create`) | `TM.TestCases` | Conditional scopes: see [testcases](#conditional-test-manager-scopes) |
| `testsets` (all commands), `schedules` | `TM.TestSets` | Conditional scopes: see [testsets](#conditional-test-manager-scopes) |
| `executions`, `testcaselog`, `teststeplog list`, `report get`, `wait` | `TM.TestExecutions` | `executions export --wait`, `report export --wait`: `TM.Attachments` |
| `result download` | `TM.TestExecutions` | `TM.TestSets` |
| `run --type package` | `TM.TestSets`, `TM.TestExecutions` | Orchestrator scopes (next section) |
| `requirements` | `TM.Requirements` | Conditional scopes: see [requirements](#conditional-test-manager-scopes) |
| `attachment` | `TM.Attachments` | Conditional scopes: see [attachment](#conditional-test-manager-scopes) |
| `customfield` (definitions) | `TM.CustomFieldDefinitions` | — |
| `customfield label`, `customfield value` | `TM.CustomFieldValues` | — |
| `objectlabel` | `TM.ObjectLabels` | — |
| `defects` | `TM.Defects` | `create`: `TM.TestCases` |
| `prompts` | `TM.Prompts` | — |
| `perf-scenario` | `TM.PerformanceScenarios` | Conditional scopes: see [perf-scenario](#conditional-test-manager-scopes) |

## Conditional Test Manager scopes

The following commands and options need extra scopes in addition to the base scope in the previous table. An extra scope named together with an option applies only when that option is passed.

| Command group | Command or option | Extra scope |
|---|---|---|
| `testcases` | `run` | `TM.TestSets`, `TM.TestExecutions` |
| `testcases` | `add`, `remove`, `list-testsets` | `TM.TestSets` |
| `testcases` | `link-automation`, `link-package` | `TM.TestExecutions` |
| `testcases` | `list-automations`, `list-result-history` | `TM.TestExecutions` in place of `TM.TestCases` |
| `testcases` | `bulk-create` | `TM.CustomFieldDefinitions` (custom fields in the file), `TM.Requirements` (requirement links in the file) |
| `testcases` | `group-by --field` on a custom field | `TM.CustomFieldDefinitions` |
| `testcases` | `export --wait` | `TM.Attachments` |
| `testsets` | `run --wait`, `list --include-last-execution` | `TM.TestExecutions` |
| `testsets` | `create --dynamic-labels`, `list-testcases`, `get-dynamic-assignment`, `set-execution-order`, `assign-user` | `TM.TestCases` |
| `requirements` | `generate-testcases`, `evaluate`, `find-obsolete-testcases` with `--attachment-ids`, and `export --wait` | `TM.Attachments` |
| `requirements` | `generate-testcases --create`, `find-obsolete-testcases --delete` | `TM.TestCases` |
| `attachment` | `list --test-case-keys` or `--all --object-type TestCase` | `TM.TestCases` |
| `attachment` | `list --requirement-keys` or `--all --object-type Requirement` | `TM.Requirements` |
| `attachment` | `list --all --object-type TestSet` | `TM.TestSets` |
| `attachment` | `download --execution-id` | `TM.TestExecutions` |
| `perf-scenario` | `execute`, `executions list`, `load-groups get`, `load-groups list`, `jobs list`, `robot-logs list` | `TM.PerformanceScenarioExecutions` |
| `perf-scenario` | `load-groups add --test-case-key` | `TM.TestCases` |
| `perf-scenario` | `load-groups add` without `--package-version` | `TM.TestExecutions` |

No Test Manager scope is checked for `pack` (it runs offline), `user get`, waiting on a requirement AI job (`--wait`, `--activity-id`), or the performance results commands (`perf-scenario results get`, `http-errors list`, `automation-errors list`, `transaction-metrics list`, `report generate`, `report compare`, `stop`), which only require a valid sign-in.

## Orchestrator scopes

Commands that look up folders, packages, users, or machines in Orchestrator also need Orchestrator scopes.

| Commands | Orchestrator scopes |
|---|---|
| `run --type package` | `OR.Folders.Read`, `OR.Execution.Read` |
| `testcases link-automation`, `testcases link-package`, `testcases list --automated` with a folder, `testsets set-folder --folder-path`, `testsets autoselect-packages --folder-path`, `testsets set-robot --robot-name`, `testsets set-execution-target --robot-name` | `OR.Folders.Read` |
| `testsets set-robot`, `testsets set-execution-target` with `--robot-user-key`, or with `--robot-name` on a test set that has no folder | `OR.Users.Read` |
| `testsets set-execution-target --machine-name` | `OR.Machines.Read` |
| `testsets assign-user --assignee-email`, `testcaselog assign --assignee-email` | `OR.Users.Read` |

An external application has no personal workspace, so `--folder-path` takes the full folder path, or `--folder-key` identifies the folder.

## Ready-to-use scope lists

### CI: run every test in an uploaded package

The scopes for `uip tm run --type package`:

```text
TM.Projects TM.TestSets TM.TestExecutions OR.Folders.Read OR.Execution.Read
```

`uip tm run` does not upload the package. A pipeline that uploads it first with [`uip or packages upload`](./uip-or-packages.md) under the same sign-in requires `OR.Execution` in place of `OR.Execution.Read`.

### Every `uip tm` command group

```text
TM.Projects TM.TestCases TM.TestSets TM.TestExecutions TM.Requirements TM.Attachments TM.ObjectLabels TM.CustomFieldDefinitions TM.CustomFieldValues TM.Defects TM.Prompts TM.PerformanceScenarios TM.PerformanceScenarioExecutions OR.Folders.Read OR.Execution.Read OR.Users.Read OR.Machines.Read
```

`TM.Users` is needed only for `migration schemas`, and `TM.Administration` only for `project update --set-default`.

## Troubleshooting a 403

A 403 from a `uip tm` command typically indicates a missing scope or role. `Data.Scopes` in the `uip login status --detailed --output json` output shows the scopes the token carries, to compare with the tables on this page.

Add the missing scope to the external application in **Admin → External Applications** and sign in again with the updated `--scope` list.

When every scope is present, the application lacks a Test Manager project role or an Orchestrator folder role, or the tenant lacks the license or feature the command uses. The `Message` field of the error identifies which.

## See also

- [uip tm](./uip-test-manager.md)
- [Authentication](./authentication.md)
- [uip login](./uip-login.md)
- [uip login status](./uip-login-status.md)
