Overview
Jira is a project and issue tracking platform used by software development teams, IT operations teams, and project managers to plan work, track bugs, manage tickets, and coordinate workflows.
The Jira integration within the Wrk platform allows teams to automate issue management processes to performing workflow transitions by calling the Jira REST API through prebuilt Wrk Actions.
This document provides an overview of how Jira integrates with Wrk, how authentication works, general API behaviour, and a full list of available Wrk Actions.
Authentication
Jira supports multiple authentication methods within Wrk, allowing flexibility depending on the use case.
OAuth 2.0
Personal Access Token (PAT)
Basic Authentication
Each authentication method can be configured when creating a Jira Connected Account inside Wrk.
OAuth 2.0
When connecting Jira via OAuth:
Authentication is initiated directly inside Wrk.
Users are redirected to Atlassian to authorize access.
Wrk receives an access token that is used for all subsequent API calls.
Tokens are scoped based on the permissions granted during authorization
Personal Access Token (PAT)
For token authentication, Jira requires the token to be sent on every request in the Authorization header.
Typical header format:
Authorization: Bearer <token>
Important Notes
The token is tied to a specific user and provides access to that user’s data.
Only one active API token can exist at a time; regenerating it will break existing integrations using the old token.
Basic Authentication
Jira also supports Basic Authentication using an email address and API token.
Example:
Authorization: Basic base64(email:api_token)
How to Obtain API Tokens
API tokens for Jira Cloud can be created from the Atlassian account security settings.
Steps:
Sign in to your Atlassian account.
Navigate to Security → API Tokens.
Generate a new API token.
Copy the token and store it securely.
General API Behaviour
Jira REST API Overview
The Jira integration uses the Jira REST API, which provides endpoints for managing issues, projects, users, comments, transitions, and other workflow resources.
Base URL and response structure
Most Jira API calls return JSON responses that commonly include:
id — the internal Jira identifier
key — the human-readable issue key (example:
PROJ-123)self — the canonical API URL for the object
Jira Site URL
When configuring the Jira integration, the Jira Site URL is required.
The site URL identifies the Jira instance and is used to determine the Cloud ID, which is required for certain Jira Cloud API requests.
Example Jira Site URL:
https://your-company.atlassian.net
Pagination
Many Jira API endpoints return paginated responses when retrieving lists of records such as projects, users, issues, or comments.
Pagination is controlled using parameters such as:
startAt — the index of the first result to return
maxResults — the maximum number of results per page
The API response typically includes:
startAtmaxResultstotalisLast
To retrieve additional results, increase the startAt value and repeat the request.
JQL Search
Jira supports a powerful query language called JQL (Jira Query Language) that allows filtering and searching for issues.
JQL supports filters such as:
project
status
assignee
priority
labels
created / updated timestamps
Example JQL query:
project = "PROJ" AND status = "Open" ORDER BY created DESC
Wrk supports retrieving issues using the JQL enhanced search (POST) endpoint, which allows complex queries and large result sets.
Entity Relationships
Many Jira resources are interconnected. Common relationships include:
Issues belong to Projects
Comments belong to Issues
Issue links connect related issues
Transitions represent workflow state changes
These relationships often require IDs or keys retrieved from previous API calls.
Rate Limiting
Jira Cloud applies rate limiting to API requests to protect platform stability.
If rate limits are exceeded, Jira may return responses such as:
HTTP 429 Too Many Requests
Applications should retry requests after the delay specified in the response headers.
Available Wrk Actions
Create issue in Jira
Delete issue in Jira
Retrieve issue from Jira
Update Assign issue in Jira
Create Transition issue in Jira
Add comment in Jira
Update comment in Jira
Retrieve comments from Jira
Retrieve comment from Jira
Retrieve comments by IDs from Jira
Delete comment in Jira
Create issue link in Jira
Retrieve issue link from Jira
Delete issue link in Jira
Retrieve for issues using JQL enhanced search (POST) from Jira
Retrieve issue picker suggestions from Jira
Retrieve project from Jira
Retrieve projects paginated from Jira
Retrieve user from Jira
Retrieve user email from Jira
Retrieve all users from Jira
Retrieve fields from Jira
Retrieve issue type from Jira
Retrieve issue types for project from Jira
Retrieve all issue types for user from Jira
Retrieve transitions from Jira
Additional Resources
Jira API Overview:
https://developer.xero.com/documentation/api/accounting/overview
Authentication Documentation:
https://developer.atlassian.com/server/jira/platform/security-overview/
Jira REST API Reference:
https://developer.atlassian.com/server/jira/platform/rest/v11002/
Pagination Guide:
https://developer.atlassian.com/server/jira/platform/rest/v11002/intro/#pagination
Rate Limiting Documentation:
https://developer.atlassian.com/cloud/jira/platform/rate-limiting/