Setting Up the Integration
Step 1: Create an OAuth 2.0 Integration in Atlassian
Section titled “Step 1: Create an OAuth 2.0 Integration in Atlassian”- Go to developer.atlassian.com/console/myapps
- Click Create → OAuth 2.0 integration
- Enter a name (e.g., “NodeKAT”) and accept the terms
- In your app settings, go to Permissions and add these API scopes:
| Scope | Description |
|---|---|
read:jira-work | Read Jira issues, projects, and comments |
read:jira-user | Read user information (assignees, reporters) |
- Go to Authorization → Configure and add a callback URL (required by Atlassian, but NodeKAT uses client credentials so this can be a placeholder like
http://localhost:8080/callback) - Note your Client ID and Client Secret from the app settings page
Next Steps
Section titled “Next Steps”Provide the following credentials to your NodeKAT administrator:
- Client ID — from your Atlassian OAuth 2.0 app
- Client Secret — from your Atlassian OAuth 2.0 app
Your administrator will configure NodeKAT to use these credentials.
OAuth 2.0 Authentication
Section titled “OAuth 2.0 Authentication”NodeKAT uses the OAuth 2.0 client credentials grant to authenticate with Jira. This means:
- No user login flow is required — the integration authenticates as itself
- Tokens are managed automatically by NodeKAT
- No inbound endpoints or callback handling is needed
Token Lifecycle
Section titled “Token Lifecycle”| Phase | Behavior |
|---|---|
| Acquisition | On startup, NodeKAT exchanges client credentials for an access token via POST https://auth.atlassian.com/oauth/token |
| Auto-refresh | Tokens are refreshed proactively 5 minutes before expiry (tokens typically last 3600 seconds) |
| 401 Retry | If a request returns 401 Unauthorized, the token is refreshed immediately and the request is retried once |
| Cloud ID Discovery | If JIRA_CLOUD_ID is not set, NodeKAT auto-discovers it via GET https://api.atlassian.com/oauth/token/accessible-resources |
| Concurrent protection | An async lock prevents parallel token refreshes |
Cross-Referencing with GitHub
Section titled “Cross-Referencing with GitHub”NodeKAT supports cross-referencing between Jira and GitHub. When the GitHub integration is also configured, the GithubService.search_by_jira_id() method can find commits, PRs, and branches that reference a Jira ticket ID. This enables workflows like asking “what code changes are associated with PROJ-123?”