Jira OAuth Integration Setup Guide

This guide walks you through setting up an Atlassian OAuth 2.0 (3LO) integration for SurfSense to connect your Jira projects.

Step 1: Access the Developer Console

1. Navigate to developer.atlassian.com
2. Click your profile icon in the top-right corner
3. Select "Developer console" from the dropdown

Step 2: Create a New OAuth 2.0 Integration

1. In the Developer Console, under My apps, click the "Create" button
2. Select "OAuth 2.0 integration" from the dropdown

Step 3: Name Your Integration

1. Enter Name: SurfSense
2. Check the box to agree to Atlassian's developer terms
3. Click "Create"

ℹ️ New OAuth 2.0 integrations use rotating refresh tokens, which improve security by limiting token validity and enabling automatic detection of token reuse.

Step 4: Configure Callback URL

1. In the left sidebar, click "Authorization"
2. Under Callback URLs, enter the redirect URI:

   http://localhost:8000/api/v1/auth/jira/connector/callback

3. Click "Save changes"

ℹ️ You can enter up to 10 redirect URIs, one per line.

Step 5: Configure API Permissions

1. In the left sidebar, click "Permissions"
2. You'll see a list of available APIs including Jira API

Step 6: Configure Jira API Scopes

1. Click "Configure" next to Jira API
2. Select the "Classic scopes" tab
3. Under Jira platform REST API, select the following scopes:

4. Click "Save"

Step 7: Get OAuth Credentials

1. In the left sidebar, click "Settings"
2. Copy your Client ID and Client Secret

⚠️ Never share your client secret publicly.

Running SurfSense with Jira Connector

Add the Atlassian environment variables to your Docker run command:

docker run -d -p 3000:3000 -p 8000:8000 \
  -v surfsense-data:/data \
  # Jira Connector
  -e ATLASSIAN_CLIENT_ID=your_atlassian_client_id \
  -e ATLASSIAN_CLIENT_SECRET=your_atlassian_client_secret \
  -e JIRA_REDIRECT_URI=http://localhost:8000/api/v1/auth/jira/connector/callback \
  --name surfsense \
  --restart unless-stopped \
  ghcr.io/modsetter/surfsense:latest