Skip to main content
The Jira integration uses OAuth 2.0 (3-legged) to authenticate with Jira Cloud. Once connected, profClaw can create issues, update status, sync comments, and receive webhook notifications.

​
Setup

​
1. Create an OAuth 2.0 app in Atlassian

  1. Go to developer.atlassian.com
  2. Create a new app, select OAuth 2.0 (3LO)
  3. Add the callback URL: https://your-host/api/auth/jira/callback
  4. Enable scopes: read:jira-work, write:jira-work, offline_access

​
2. Configure environment variables

​
3. Connect via OAuth

Redirect the user to start the OAuth flow:
After authorization, the callback at /api/auth/jira/callback exchanges the code for tokens and stores them. Refresh tokens are used automatically when the access token expires.

​
Webhook Events

Register a Jira webhook to receive real-time events:
  • URL: https://your-host/api/webhooks/jira
  • Events: jira:issue_created, jira:issue_updated, comment_created
Incoming events are verified and routed to create or update local tasks.

​
Status Mapping

Jira statuses map to profClaw TicketStatus values via the sync adapter: Mapping is bidirectional. When a profClaw ticket changes status, the corresponding Jira issue updates via the Jira REST API.

​
Priority Mapping

​
Bidirectional Sync

The sync engine polls Jira for updates every 60 seconds (configurable via syncIntervalMs). Conflicts use the latest_wins strategy by default.
To enable Jira sync, configure the platform in your settings:

​
Jira Client

The JiraClient class (src/integrations/jira-client.ts) wraps the Jira REST API v3:
  • createIssue(fields) - Create a new Jira issue
  • updateIssue(issueKey, fields) - Update fields on an existing issue
  • transitionIssue(issueKey, transitionId) - Change issue status
  • addComment(issueKey, body) - Add a comment
  • getIssue(issueKey) - Fetch a single issue
  • searchIssues(jql, options) - JQL search with pagination