> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/saas-applications/testrail.md). # TestRail The TestRail integration connects your test management platform to Harmony, giving your team visibility into user access, roles, and seat allocation across your organization. Once connected, Harmony pulls user and license data from your TestRail instance so you can monitor who has access and how seats are being used. TestRail appears as a managed application in Application Management. #### What the TestRail integration enables | Capability | Description | | ---------------------- | ---------------------------------------------------------------------------------------------- | | User Discovery | Surface every TestRail user - both active and deactivated - in Harmony's software inventory | | Seat Visibility | See which users hold a paid TestRail seat, so you can identify seats to reclaim | | Role Labels | Record the role label TestRail reports for each user (TestRail roles are defined per instance) | | Multi-Instance Support | Connect multiple TestRail instances for organizations that run more than one | *** #### Prerequisites 1. **TestRail Cloud** - Harmony connects to `https://.testrail.io`. Self-hosted TestRail Server instances are not supported 2. **A TestRail administrator account** - as of TestRail 6.6, only administrators can list all users through the API. A non-administrator credential is rejected with `403 Forbidden` and no TestRail data is synced 3. **API access enabled in TestRail** - the API can be switched off for the whole instance under **Admin** > **Site Settings** > **API** 4. **Your TestRail subdomain** - the `mycompany` part of `mycompany.testrail.io` 5. **A Harmony account** with admin privileges *** #### Connect TestRail to Harmony **Step 1: Generate a TestRail API key** Sign in to TestRail as the administrator account you want Harmony to use, then: 1. Open **My Settings** 2. Click the **API Keys** tab 3. Click **Add Key** 4. Enter a **Name** describing where the key will be used (for example `Harmony Integration`) 5. Click **Generate Key** 6. **Copy the API key** - TestRail displays it only once and it can no longer be retrieved through the interface 7. Click **+ Add Key** 8. Click **Save Configuration** {% hint style="warning" %} **Step 8 is required.** If you generate and copy the key but never click **Save Configuration**, TestRail does not store the key. It will then fail to authenticate when you enter it in Harmony, with no indication of why. {% endhint %} {% hint style="info" %} Generate the key while signed in as the administrator account you intend to use - a TestRail API key inherits the permissions of the user who created it (see [Permissions Explained](#permissions-explained) below). {% endhint %} **Step 2: Navigate to Integrations** 1. Log in to your Harmony dashboard 2. Go to **Settings** > **Integrations** 3. Find **TestRail** under **SaaS Applications**, or search for it by name 4. Click **Connect** **Step 3: Enter Credentials** 1. **Instance subdomain** - your TestRail subdomain (for example `mycompany` if your TestRail URL is `mycompany.testrail.io`) 2. **Admin email** - the email address of the TestRail administrator account that generated the API key 3. **API key** - the key you copied in Step 1 4. Click **Connect** Once connected, Harmony begins syncing user and license data from your TestRail instance. *** #### Disconnect TestRail from Harmony 1. Log in to your Harmony dashboard 2. Go to **Settings** > **Integrations** 3. Find **TestRail** under **SaaS Applications** and click the integration card 4. Click **Disconnect** 5. Confirm the disconnection when prompted Once disconnected, Harmony stops syncing data from TestRail. Previously synced data remains available in Harmony. You can also revoke the key in TestRail under **My Settings** > **API Keys**. *** #### What Harmony Syncs from TestRail | Data | Description | | ------------- | ---------------------------------------------------------------------------------------- | | User profiles | TestRail user ID, name, and email address | | Status | Whether the user is active or deactivated in TestRail | | Seat usage | Active users are recorded as holding a paid seat; deactivated users are recorded as free | | Role label | The role name TestRail reports for the user, plus its role ID | | Account flags | Administrator flag, MFA requirement, SSO enabled, and TestRail group IDs | {% hint style="info" %} **Deactivated users are still inventoried.** Harmony collects users whose TestRail status is inactive as well as active ones, and marks them accordingly - deactivated accounts that still occupy a seat are exactly what license reclamation needs to see. {% endhint %} {% hint style="info" %} **About TestRail roles.** TestRail roles are defined per instance - a customer can rename or create them freely - and the TestRail API exposes no permission meaning for a role beyond the administrator flag. Harmony records the role label TestRail reports as-is and does not classify TestRail users as administrators. TestRail roles are not surfaced in Harmony's access reviews, where they read as not collected. {% endhint %} {% hint style="info" %} **No activity or login data.** TestRail's API has no login, session, or audit endpoint, and user records carry no last-login timestamp. Harmony therefore does not collect last-login dates or usage activity for TestRail. TestRail's audit log is a TestRail Enterprise administration feature that is not available over the API. {% endhint %} {% hint style="info" %} **Sync cadence:** the TestRail user inventory is refreshed every 6 hours. {% endhint %} *** #### Viewing TestRail Data in Harmony * **Application Management** - TestRail appears as a managed application, where you can review its user list and seat counts * **User profiles** - individual users show their TestRail access alongside other application data {% hint style="info" %} TestRail's API exposes no pricing or billing data. Any cost figures shown against TestRail in Harmony come from your own contract and spend data in Harmony, not from TestRail. {% endhint %} *** #### Managing Access and Licenses With TestRail connected as a managed application, you can: * Identify which users hold TestRail access and which of them still occupy a paid seat * Spot deactivated TestRail accounts that are still on the roster, so seats can be reclaimed * Compare TestRail access against your organization's broader SaaS footprint *** #### Permissions Explained Harmony authenticates to TestRail with HTTP Basic authentication, using the administrator email address and the API key you provide. All access is read-only. | What Harmony calls | Why | | ----------------------- | ----------------------------------------------------------------------------------------------------------------- | | `GET /api/v2/get_users` | Lists every user in the TestRail instance - the source of the user inventory, status, seat usage, and role labels | Things to know about the key: * **TestRail API keys carry no scopes.** A key inherits the full permissions of the TestRail user who created it, so a key generated by an administrator is as powerful as that administrator's account. There is no way to narrow a key to a subset of TestRail data * Because listing all users requires an administrator, the credential Harmony uses is necessarily an administrator credential * You can generate multiple keys for different tools and revoke any of them individually at any time under **My Settings** > **API Keys**, without changing the account password * Harmony only reads user data. It does not create, modify, or remove TestRail users, roles, projects, or test data *** #### Troubleshooting
The connection is rejected or no data appears **Possible causes:** * The API key was generated but **Save Configuration** was never clicked, so TestRail never stored it * The email address does not match the TestRail account that generated the key * The API is disabled for the whole instance under **Admin** > **Site Settings** > **API** * The subdomain is wrong - Harmony expects only the `mycompany` part of `mycompany.testrail.io` **Solutions:** 1. Regenerate the key following all of [Step 1](#step-1-generate-a-testrail-api-key), including **+ Add Key** and **Save Configuration** 2. Confirm the email address is the login of the account that created the key 3. Ask a TestRail administrator to confirm the API is enabled under **Admin** > **Site Settings** > **API**
The sync fails with an access denied error **Possible causes:** * The connected account is not a TestRail administrator. As of TestRail 6.6, only administrators can list all users through the API, and TestRail returns `403 Forbidden` for anyone else **Solutions:** 1. Reconnect the integration using an API key generated by a TestRail administrator account 2. There is no partial mode - without an administrator credential, no TestRail users are synced at all
A sync fails during TestRail's daily maintenance window **Possible causes:** * TestRail Cloud instances undergo a daily maintenance window, during which the API returns `409` with the message `Account is undergoing daily maintenance` **Solutions:** 1. No action is needed - the affected sync fails and Harmony retries at the next scheduled sync, six hours later 2. This applies to TestRail Cloud only
Sync appears slow, or TestRail reports rate limiting **Possible causes:** * TestRail rate limits the API to 180 requests per minute on Cloud Professional and 300 per minute on Cloud Enterprise. The limit is **per instance**, not per key - Harmony shares it with anything else calling your TestRail API, such as your own CI pipelines submitting test results **Solutions:** 1. Harmony paces its requests and honours TestRail's `Retry-After` response when rate limited, so a busy instance simply takes longer to sync 2. If your CI pipelines are heavy API users, expect the shared budget to slow both sides during peak periods
A self-hosted TestRail Server instance will not connect **Possible causes:** * Harmony builds the API address as `https://.testrail.io`, so it can reach TestRail Cloud instances only. Self-hosted TestRail Server installations run on customer-chosen hostnames and are not supported **Solutions:** 1. This integration requires TestRail Cloud
Rotating the API key To rotate, generate a new key in TestRail under **My Settings** > **API Keys**, disconnect the TestRail integration in Harmony, reconnect with the new key, and then delete the old key in TestRail.
*** #### Data & Privacy
Key privacy principles For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy). * Harmony accesses TestRail data in read-only mode and does not modify any data in your TestRail account * The integration can be revoked at any time by disconnecting it in Harmony or deleting the API key in TestRail
What Harmony does not collect Harmony reads only TestRail's user list. It does not collect: * Test cases, test case titles, test runs, test results, or result comments * Attachments or any other project content * IP addresses - TestRail's user and activity records do not carry them * Login, session, or audit data - TestRail exposes no such API
--- # 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://docs.harmony.io/integrations/saas-applications/testrail.md?ask=&goal= ``` `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.