Skip to main content
Connect to Jira using OAuth authentication for Jira Software, Work Management, and Service Management
This guide walks you through connecting to your Jira workspace using a dedicated service account to enable configuration management and status mapping across all Jira products.

​
Prerequisites

Before you begin, ensure you have:
  • Admin access to your Jira workspace
  • Active Jira projects (Software, Work Management, or Service Management)
  • Atlassian account with appropriate permissions
Atlassian User Directory requirement: Users must exist in your Atlassian User Directory for Ravenna to sync them and match them with Ravenna profiles. This is required for correctly mapping users to ticket roles (reporter, assignee, etc.). If a ticket is opened by someone not in your user directory, the request will be created as unassigned with an internal note containing the user’s email.

​
Service account setup

Create a dedicated service account for Ravenna to perform actions in Jira:
1

Create Jira service account

  1. Go to your Atlassian Admin page
  2. Navigate to Users and create a new user account
  3. Name it clearly (e.g., “Ravenna Bot” or “Ravenna Service Account”)
  4. Save the account credentials
2

Assign required roles

Permissions
For Jira Service Management:
  • In the Atlassian User Director, grant the User (Agent) and User Access Admin roles.
  • In your Jira Service Desk Space Settings > Access > People and access > add the newly created Service Account and grant the Service Desk Team and Administrators roles.
For Jira:
  • In the Atlassian User Director, grant the User and User Access Admin roles.
  • In your Jira Space Settings > Access > add the newly created Service Account and grant the Administrator roles.
It’s best to add the Service Account to each Space that you want it to have access to. Your organization might already make use of Atlassian groups to grant certain roles, so it could be quicker to add the Service User to that group in order for it to automatically be given the needed Jira roles and Space roles.
3

Verify permissions

Ensure the service account has:
  • Read/write access to tickets and issues
  • Read access to users and knowledge base articles (for JSM)
  • Permission to add comments and transition issues
The service account will directly perform actions in Jira to create, update, and query information about tickets. All actions triggered by Ravenna will be taken by this account.

​
Setup guide

1

Navigate to integrations

  1. Go to Settings > Integrations
  2. Find Jira in the Ticketing section
2

Select Jira integration

Click Connect on the Jira integration card
3

Authorize with Atlassian

  1. You’ll be redirected to Atlassian’s authorization page
  2. Log in with your service account credentials
  3. Select your Jira site from the dropdown
  4. Review the requested permissions:
    • Read and write issues and requests
    • Read projects and service desks
    • Read and write comments
    • Manage webhooks
  5. Click Accept to grant access
4

Complete setup

After authorization, you’ll be redirected back with the integration connected. All your Jira projects will be available.

​
Troubleshooting

Cause: Insufficient permissions or expired sessionSolution:
  • Ensure you’re logging in with the service account credentials
  • Verify the service account has admin permissions in your Jira site
  • Try disconnecting and reconnecting the integration
  • Clear browser cache and retry authorization
  • Verify your Jira site is accessible
Cause: Projects not accessible or integration needs refreshSolution:
  • Refresh the integration by disconnecting and reconnecting
  • Ensure your Jira site has active projects
  • Verify the service account has access to the projects/service desks
  • Check project permissions in Jira admin
  • For JSM: Ensure service desk projects are not archived
Cause: Service desk configuration or permissions issueSolution:
  • Verify the service desk has published request types
  • Check that request types are not hidden or restricted
  • Ensure the service account has service desk agent permissions
  • Confirm the jira-servicedesk-users and Service Desk Team roles are assigned
  • Refresh the integration to fetch latest configuration
Cause: OAuth authorization missing required permissionsSolution:
  • Verify the OAuth authorization granted all required permissions
  • Re-authorize the integration with full permissions
  • Check Jira site settings for app restrictions
  • Ensure the service account has appropriate admin/agent access
  • Verify service account roles in Atlassian Admin
Cause: The user does not exist in your Atlassian User Directory, or they don’t have permissions on the specific project/space to open issues.Solution:
  • Verify the user exists in your Atlassian User Directory
  • Invite the user to your Atlassian account if they’re missing
  • Check that the user has the required permissions on the specific Jira project or JSM space to create issues
  • Review project permission schemes in Jira admin settings

​
Features

Once connected, you can enable Jira settings:
https://mintcdn.com/ravenna/sHkIxR1kZRcsw3Gd/icons/jira.svg?fit=max&auto=format&n=sHkIxR1kZRcsw3Gd&q=85&s=01fea6b649834bc1b3d27ec06578b733

Ticket Sync

Bidirectional sync of tickets and issues, including comments, status changes, and assignee updates