Skip to main content

Creating an Atlassian OAuth 2.0 App with Jira Integration

This guide demonstrates how to create and configure an OAuth 2.0 application in the Atlassian Developer Console with comprehensive Jira API access. This setup enables developers to build integrations that can read and modify Jira projects, issues, comments, and other work data programmatically.

What This Enables​

By following this guide, you'll create an application that can:

  • Automate Jira workflow management and issue tracking
  • Build custom dashboards that aggregate data across multiple Jira projects
  • Create integrations between Jira and external systems (CRM, monitoring tools, etc.)
  • Develop custom reporting and analytics solutions
  • Synchronize project data between Jira and other project management tools

Prerequisites​

Before beginning, ensure you have:

  • An active Atlassian account with developer privileges
  • Access to the Atlassian Developer Console
  • Understanding of OAuth 2.0 authentication flow

Configuration Process​

1. Access the Developer Console​

Navigate to developer.atlassian.com and authenticate with your Atlassian credentials. After you log in, locate the Console section and select My apps from the navigation menu.

2. Initialize Your Application​

  1. From the "My apps" dashboard, click Create.
  2. When prompted to select an integration type, choose OAuth 2.0 integration.
  3. Configure the basic application metadata:
    • App name: Use a descriptive identifier, such as "Jira Management Gateway"
    • Description: Provide a clear explanation of your application's intended functionality

3. Configure Application Settings​

After creation, you'll be directed to the application overview page. Record the automatically generated App ID (formatted as a UUID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). This identifier will be required for API authentication.

If your application will operate across multiple Atlassian sites, set the Distribution status to "Sharing."

4. Configure OAuth Authorization​

In the left navigation panel, select Authorization. Configure the OAuth callback endpoint by entering your application's callback URL in the Callback URL field:

https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

This endpoint will receive the authorization code during the OAuth flow.

5. Define API Permissions​

The authorization configuration requires specific scopes that define your application's access permissions. Add the following scopes to enable comprehensive Jira functionality:

Core Jira Operations​

  • read:jira-work - Enables reading Jira work data including issues, projects, and workflows
  • write:jira-work - Allows modification of Jira work items and project data

User Management​

  • read:jira-user - Provides access to user profiles and account information

Project Administration​

  • read:project:jira - Grants read access to project configurations and metadata
  • write:project:jira - Enables project creation, modification, and configuration changes

Issue Management​

  • read:issue:jira - Allows reading issue details, status, and metadata
  • write:issue:jira - Enables issue creation, updates, and status transitions

Comment System​

  • read:comment:jira - Provides access to issue comments and activity logs
  • write:comment:jira - Allows adding and modifying issue comments

Dashboard Access​

  • read:dashboard:jira - Enables reading dashboard configurations and data
  • write:dashboard:jira - Allows dashboard creation and modification

Field Configuration​

  • read:field:jira - Provides access to custom fields and field schemas
  • write:field:jira - Enables custom field creation and configuration

Filter Management​

  • read:filter:jira - Grants access to saved searches and filters

6. OAuth URL Generation​

Once all scopes are configured, Atlassian automatically generates authorization URLs for different API categories:

  1. Granular Jira API authorization URL - For applications requiring fine-grained permission control
  2. Classic Jira Service Management API authorization URL - For service desk and incident management integrations
  3. Classic Jira platform REST API authorization URL - For traditional Jira REST API operations
  4. User Identity API authorization URL - For user authentication and profile access
  5. Granular Confluence API authorization URL - For Confluence integration (optional)

7. Finalize Configuration​

Click Save changes to validate and apply your scope configuration. The system will verify all settings and update your application registration.

8. Retrieve OAuth Credentials​

Navigate to the Settings section in the left sidebar to obtain your OAuth credentials:

  • Client ID: Public identifier used in authorization requests (safe for client-side code)
  • Client Secret: Private authentication key (must remain secure on server-side only)

Security Critical: The Client Secret must never be exposed in client-side code, public repositories, or browser environments. Store these credentials in secure server-side configuration.

OAuth 2.0 Implementation​

Authorization Flow​

Your OAuth implementation will follow this sequence:

1. User Authorization Request​

Direct users to the generated authorization URL, which includes:

  • Your Client ID
  • Requested scope permissions
  • Callback URL configuration
  • State parameter (recommended for CSRF protection)

2. Authorization Code Exchange​

When users approve your application, they're redirected to your callback URL with an authorization code. Exchange this code for access tokens using these parameters:

Token Request Configuration:

  • grant_type: authorization_code
  • client_id: Your application's Client ID
  • client_secret: Your application's Client Secret
  • code: The authorization code from the callback
  • redirect_uri: Your configured callback URL

Token Endpoint: https://auth.atlassian.com/oauth/token

3. API Authentication​

Use the received access token for API requests by including it in request headers:

Authorization: Bearer {access_token}

Base API URL: https://api.atlassian.com/ex/jira/{cloudid}/rest/api/3/

4. Token Maintenance​

Access tokens have limited lifespans. Implement automatic token refresh using the refresh token with your Client ID and Client Secret to maintain continuous API access without requiring user re-authorization.

Troubleshooting Common Issues​

Scope Configuration Problems​

  • Unrecognized scope errors: Verify scope names match exactly as specified in this guide
  • Permission denied responses: Ensure all required scopes are properly configured and approved

Authorization Failures​

  • Callback URL mismatches: Confirm your callback URL is correctly configured and publicly accessible
  • Invalid client credentials: Verify Client ID and Client Secret are correctly implemented

Token Management Issues​

  • Expired token errors: Implement robust token refresh logic using the refresh token
  • Authentication failures: Ensure proper header formatting and token inclusion in API requests

Capabilities Summary​

This configuration provides your application with comprehensive Jira access including:

  • Project Management: Create, read, update, and delete projects and their configurations
  • Issue Lifecycle: Full CRUD operations on issues, including status transitions and field updates
  • Collaboration: Comment management and user interaction capabilities
  • Reporting: Dashboard access for custom analytics and reporting features
  • Customization: Field and filter management for tailored workflows
  • User Integration: Access to user profiles and account information

Next Steps​

  1. Implement OAuth Flow: Integrate the authorization flow into your application using your preferred programming language and framework
  2. API Integration Testing: Validate your implementation with test API calls using the obtained access tokens
  3. Error Handling: Implement comprehensive error handling for token refresh, rate limiting, and API failures
  4. Production Deployment: Deploy your application with secure credential management

Additional Resources​

For detailed implementation guidance, consult the official Atlassian documentation:

Your Atlassian application is now configured with enterprise-grade Jira permissions and ready for production integration.