From 10.8 onwards, TestRail supports two methods for authenticating external tools and integrations: OAuth 2.0 and API keys. Both methods are available and can be used simultaneously — OAuth 2.0 is an additional option, not a replacement for API keys. The ability to generate API access tokens — including both API keys and OAuth 2.0 tokens — is controlled by a role permission. See Managing user permissions and roles for details.
Administrators can view and revoke all active tokens and API keys from a central Access Management dashboard in Site Settings.
How OAuth 2.0 authentication works
When an OAuth 2.0-enabled tool connects to TestRail for the first time:
- Your browser opens to the TestRail authorization screen.
- You enter your TestRail instance name.
- You sign in to your TestRail account.
- The authorization screen shows the tool's name and the permissions it is requesting:
- Test data — Access and act on your TestRail projects and data within your existing permissions
- File attachments — Upload and download file attachments within your TestRail projects
- Profile — View your name, email address and profile information
- Click Allow Access to grant the tool access to your account.
The tool receives a token scoped to the permissions approved. Subsequent connections use the stored token — you will not be prompted to sign in again unless the token is revoked or expires.
Managing access tokens — administrators
Viewing all tokens
Go to Site Settings > API > Access Management.
The dashboard lists all active OAuth 2.0 tokens and API keys across your instance:
| Column | Description |
|---|---|
| Name | Token or key name |
| Type | OAuth 2.0 or API Key |
| Created by | The user who authorized or generated the token |
| Last used | Date and time of the most recent API call |
| API Calls | Total number of API calls made |
Revoking a token
- In the Access Management dashboard, find the token you want to revoke.
- Click Revoke.
- Confirm in the dialog that appears.
Managing your own tokens — users
Viewing your tokens
Go to My Settings > API Keys.
All your active API keys and OAuth 2.0 tokens are listed here. If an administrator has revoked one of your tokens, a notification appears at the top of the list.
Generating an API key
- Go to My Settings > API Keys.
- Click Add API Key.
- Enter a name for the key and click Generate.
- Copy the key immediately — it is shown only once.
Revoking your own token or key
- Go to My Settings > API Keys.
- Click Revoke next to the token or key and confirm.
Note: Revoking a token or key immediately disables access for any tool using it.