Getting Started with Xray for Jira: Setup, Test Configuration, and API Keys

#qa #testing #jira #automation

If you're building test automation, integrating CI/CD pipelines, or working with AI-driven QA workflows, setting up Xray correctly is the first step.

This guide walks you through the full setup—from installation to generating API credentials you can use in automation.

What Is Xray?

Xray Test Management is a powerful test management app that integrates directly with Jira. It allows teams to manage manual and automated tests, track execution results, and connect testing to requirements and defects.

Step 1 — Install Xray in Jira

Log in to your Jira Cloud instance
Click the Settings icon (gear)
Select Apps or Manage apps
Click Find new apps
Search for Xray Test Management
Click Try it free or Install

After installation, Xray will be added to your Jira environment.

Note: You must be a Jira administrator to install apps.

Step 2 — Create a Test Issue Type in Jira

Xray stores test cases as a special issue type called Test. If your Jira instance does not already have this issue type, you must create it.

Go to Space Settings
Click Add work type
Name it Test
Select an icon and click Create

Step 3 — Link the Jira Test Issue Type to Xray

After creating the Test issue type, ensure Xray recognizes it.

Open Jira Settings
Navigate to Apps
Open Xray settings
Locate Issue Type Mapping or Test Issue Configuration
Confirm that the Test issue type is mapped as an Xray Test

This allows Xray to treat those issues as test cases.

Step 4 — Generate Client ID and Client Secret

To use Xray’s REST API (for automation tools or scripts), you need authentication credentials.

In Xray settings, find the API Keys or API Access section
Click Create API Key or Generate Credentials
Copy the Client ID
Copy the Client Secret
Store both values securely

Important: The Client Secret is sensitive and may not be shown again.

Step 5 — Use the Credentials (API Example)

Once you have your credentials, you can authenticate with Xray and start using its APIs.

Here’s a simple example to get an authentication token:


bash
curl -X POST "https://xray.cloud.getxray.app/api/v2/authenticate" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'