JIRA Integration Setup Guide

Complete guide to setting up JIRA Software or JIRA Service Management integration with SecureHive

Documentation

Prerequisites Choosing Your JIRA Product Setting Up Your JIRA Account Creating an API Token Configuring Webhooks Configuring in SecureHive Verifying the Integration Troubleshooting Security Best Practices

Prerequisites

What you need before starting the integration setup

A JIRA account (Cloud or Server/Data Center)
Admin access to your JIRA instance
Your SecureHive tenant ID

This integration supports both JIRA Software (Plan & Track) and JIRA Service Management (Support & Fix). The setup process is identical for both.

Choosing Your JIRA Product

Understanding the differences between JIRA Software and JIRA Service Management

JIRA Software

Plan & Track - Best for software development teams

TaskBugStoryEpic

Use Case: Tracking development work, technical issues, feature requests

JIRA Service Management

Support & Fix - Best for IT service management

IncidentService RequestProblemChange Request

Use Case: Security incidents, IT service requests, operational issues

Both products use the same API and authentication, so the integration works identically with either one.

Setting Up Your JIRA Account

Create or access your JIRA instance and configure your project

Create or Access Your JIRA Instance

If you don't have a JIRA account, sign up at atlassian.com/software/jira

For new accounts:

Sign up for a free trial or purchase a plan
Create your JIRA instance (e.g., yourcompany.atlassian.net)

For existing accounts:

Log in to your JIRA instance
Ensure you have admin permissions

Create a Project

Create a project in JIRA for SecureHive integration

For JIRA Software:

Go to Projects → Create project
Select Software → Choose a template (Scrum, Kanban, etc.)
Enter a project name and key (e.g., "SEC" for Security)
Click Create

For JIRA Service Management:

Go to Projects → Create project
Select Service Management → IT Service Management or Business Service Management
Choose a template (e.g., "IT Service Desk")
Enter a project name and key (e.g., "ITSD" or "SD")
Click Create

Get Your Project Key

The project key is visible in the URL when viewing your project

Example URL:

https://yourcompany.atlassian.net/browse/PROJECT-KEY-123

The project key is the part before the dash (e.g., "PROJECT-KEY" in the example above)

Save this key - you'll need it when configuring the integration

Identify Available Issue Types (Work Types)

Important: In the JIRA UI, this is called "Work type" (newer terminology), but in the API it's called "Issue type". They refer to the same thing.

For JIRA Software projects:

Common work types: Task, Bug, Story, Epic
Default: Task (works for most use cases)

For JIRA Service Management projects:

Common work types: Incident, Service Request, Problem, Change Request
Recommended: Incident (for security/operational issues)

To find available work/issue types:

Go to your project in JIRA
Click Create to create a new issue/work item
Look at the "Work type" dropdown (required field with asterisk *)
Note the available options (e.g., "Task", "Incident", "Service Request")
Save the exact work type name - you'll need it when configuring the integration in SecureHive

Creating an API Token

Generate and format your JIRA API token for SecureHive authentication

Generate an API Token

JIRA uses API tokens for authentication instead of passwords

Log in to your JIRA instance
Click on your profile picture/avatar in the top right corner
Select Account settings
In the left sidebar, click Security
Scroll down to the API tokens section
Click Create API token
Give it a label (e.g., "SecureHive Integration")
Click Create

IMPORTANT: Copy the token immediately - you won't be able to see it again!

Format Your API Credentials

For SecureHive, you need to format your API token as: email:token

Format Requirements:

EmailYour JIRA account email

your.email@example.com

TokenThe API token you created

ATATT3xFfGF0a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Combined FormatNo spaces

your.email@example.com:ATATT3xFfGF0a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Save this formatted string - this is what you'll enter as the "API Key" in SecureHive.

Get Your Base URL

Your JIRA base URL is simply your JIRA instance URL

Format: https://yourcompany.atlassian.net

Do not include:

A trailing slash
/rest/api/3 or any other path

Examples:

Cloud: https://mycompany.atlassian.net
Server/Data Center: https://jira.mycompany.com

Configuring Webhooks in JIRA

Set up webhooks to allow JIRA to notify SecureHive when issues are updated

Important: You must create the integration in SecureHive first (see next section) before you can get the webhook URL.

Get Your SecureHive Webhook URL

When you create the integration in SecureHive, the system automatically generates a webhook URL

To find your webhook URL:

Go to Settings → Integrations → Service Management
Find your integration in the list
Click on the integration card or use the Edit button to view details
The Webhook URL will be displayed in the integration details

The URL format is: {API_BASE_URL}/integrations/service-management/webhooks/{your-tenant-id}

Create a Webhook in JIRA

Configure the webhook in your JIRA instance

In JIRA, click the Settings (gear icon) in the top right
Select System (for JIRA Cloud) or Administration (for Server/Data Center)
In the left sidebar, under ADVANCED, click Webhooks
Click Create a webhook
Fill in the details:
- Name: SecureHive Integration
- Status: Enabled
- URL: Paste your SecureHive webhook URL from Step 1
- Description: (Optional) Integration with SecureHive for issue synchronization
Under Events, select:
- ✅ Issue created
- ✅ Issue updated
- ✅ Issue deleted (optional)
- ✅ Worklog updated (optional)
Under Exclude body, leave it unchecked (SecureHive needs the full payload)
Click Create

Configuring the Integration in SecureHive

Complete the integration setup in SecureHive using the information you've gathered

Required Information Checklist

JIRA base URL (e.g., https://yourcompany.atlassian.net)
Project key (e.g., ITSD or SEC)
API token formatted as email:token
Issue type (see recommendations below)

Navigate to Integration Settings

Go to the Service Management Integrations page

Navigation Path:

Log in to SecureHive
In the left sidebar, expand the Administration section
Under Administration, expand the Admin section
Click on Integrations

Alternative - Direct URL:

/s/{your-tenant}/settings/integrations/service-management

Replace {your-tenant} with your tenant identifier (visible in your current URL).

Fill in the Integration Form

Enter the required information to create the integration

Platform TypeRequired

JIRA

Platform NameRequired

JIRA ServiceDesk - Production

Base URLRequired

https://yourcompany.atlassian.net

Authentication TypeRequired

API_KEY

API KeyRequired

your.email@example.com:ATATT3xFfGF0...

Configure Advanced Settings

Set the project key and issue type

Required Fields:

Project KeyRequired

ITSD

Issue TypeRequired

Incident

Issue Type Selection Guide:

JIRA Product	Recommended Issue Type	When to Use
JIRA Software	`Task`	General security issues, compliance tasks
JIRA Software	`Bug`	Security vulnerabilities, technical defects
JIRA Service Management	`Incident`	Security incidents, operational issues
JIRA Service Management	`Service Request`	Policy requests, access requests

Note: The issue type name must match exactly (case-sensitive) what appears in your JIRA project.

Test the Connection

Verify your configuration is correct

After saving, use the Test Connection button to verify:

Your credentials are correct
The API token has proper permissions
The base URL is accessible

If the test fails, check:

API token format is correct (email:token)
API token hasn't expired
Your JIRA account has proper permissions
Base URL is correct and accessible

Activate the Integration

Enable the integration to start syncing issues

Ensure Active toggle is enabled
The integration status should change to ACTIVE after successful configuration

Verifying the Integration

Test that the integration is working correctly

Test Issue Creation

Create a test issue in SecureHive
The issue should automatically sync to JIRA
Check your JIRA project to verify the issue was created

Test Webhook Reception

Update an issue in JIRA that was synced from SecureHive
Check SecureHive logs or the synced issue details to verify the webhook was received
The issue status should update in SecureHive

Troubleshooting Common Issues

Solutions to common integration configuration problems

1. Authentication Failed

The API token authentication is not working

• Verify API token format: email:token (no spaces)
• Ensure the API token hasn't been revoked
• Check that your JIRA account has proper permissions

2. Project Not Found

The specified project cannot be found in JIRA

• Verify the project key is correct (case-sensitive)
• Ensure the project exists in your JIRA instance
• Check that your account has access to the project

3. Webhook Not Receiving Events

JIRA webhooks are not reaching SecureHive

• Verify the webhook URL is correct in JIRA
• Check that webhook events are enabled in JIRA
• Verify your SecureHive instance is accessible from the internet
• Check SecureHive logs for webhook reception errors

4. Issue Type Not Found

The specified issue type doesn't exist in your JIRA project

• Verify the issue type name matches exactly (case-sensitive)
• For JIRA Software: Common types are "Task", "Bug", "Story", "Epic"
• For JIRA Service Management: Common types are "Incident", "Service Request", "Problem", "Change Request"
• Check available issue types in your JIRA project settings:
1. Go to Project Settings → Issue types
2. Verify the exact name (including capitalization)
3. Use the exact name in your integration configuration

Getting Help

If you encounter issues, try these steps:

Check the SecureHive integration logs
Verify all credentials and URLs
Test the JIRA API connection using curl:

curl -u "your.email@example.com:YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  https://yourcompany.atlassian.net/rest/api/3/myself

This should return your JIRA user information if the credentials are correct.

Security Best Practices

Security recommendations for maintaining a secure integration

API Token Security

Never share your API token
Use a dedicated service account if possible
Rotate tokens periodically
Revoke tokens that are no longer needed

Webhook Security

Use HTTPS for webhook URLs
Configure webhook secrets
Monitor webhook logs for suspicious activity

Permissions

Use the principle of least privilege
Grant only necessary permissions to the integration account
Regularly review and audit permissions