Three things burned me building a Jira integration for IssueCapture that the official docs don't warn you about: ADF for descriptions, refresh token rotation, and cloud_id discovery. What I expected to be a two-day integration took considerably longer.

This covers all three, plus the OAuth 2.0 flow end to end.

OAuth 2.0 (3LO): The Full Flow

Jira Cloud uses three-legged OAuth 2.0. No API tokens for SaaS integrations — you need actual user consent.

Step 1: Build the authorization URL

const params = new URLSearchParams ({ audience : ' api.atlassian.com ' , client_id : process . env . ATLASSIAN_CLIENT_ID , scope : ' read:jira-user read:jira-work write:jira-work offline_access ' , redirect_uri : ' https://yourapp.com/oauth/callback ' , state : crypto . randomUUID (), response_type : ' code ' , prompt : ' consent ' , });

const authUrl = `https://auth.atlassian.com/authorize? ${ params } ` ;

Enter fullscreen mode

Exit fullscreen mode

offline_access is required if you want a refresh token.…