Setup

Connect to Jira using OAuth authentication with a dedicated user account

Connect to Jira using OAuth authentication for Jira Software, Work Management, and Service Management

This guide walks you through connecting your Jira workspace using a dedicated Atlassian user 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
• An available user seat in your Atlassian organization for the dedicated Ravenna account

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.

Create a dedicated user account

Ravenna needs a standard Atlassian user account (with a user seat) to perform actions in Jira. This account acts on behalf of Ravenna when creating tickets, adding comments, and transitioning issues, so the account’s display name is visible across Jira on any action Ravenna takes.

Do not use an Atlassian Managed Service Account. Atlassian offers a “service account” feature under organization-level admin settings. These managed service accounts have restricted API access and will not work with Ravenna. You need to create a regular user account with a standard user seat.

1. Create a new Atlassian user

   1. Go to your Atlassian Admin page
   2. Navigate to Users and create a new user account
   3. Choose a display name that your team will recognize as Ravenna (e.g., “Ravenna” or “Ravenna Bot”). This name appears as the reporter and commenter on Jira tickets, so pick something clear for your team.
   4. Save the account credentials securely
2. Assign required roles

   

   For Jira Service Management:

   • In the Atlassian User Directory, grant the User (Agent) and User Access Admin roles.
   • In your Jira Service Desk Space Settings > Access > People and access, add the Ravenna account and grant the Service Desk Team and Administrators roles.

   For Jira Software or Work Management:

   • In the Atlassian User Directory, grant the User and User Access Admin roles.
   • In your Jira Space Settings > Access, add the Ravenna account and grant the Administrator role.

   Add the Ravenna account to each Jira space you want it to access. If your organization uses Atlassian groups to manage roles, adding the Ravenna account to the appropriate group can automatically grant the needed Jira and space roles.
3. Verify permissions

   Ensure the Ravenna 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

Ravenna performs all actions in Jira through this account. Any ticket created, comment added, or status change made by Ravenna will appear under this account’s name in Jira.

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 the dedicated Ravenna user account credentials (not your personal account)
   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

Authorization fails

Cause: Insufficient permissions, expired session, or wrong account type

Solution:

• Ensure you’re logging in with the dedicated Ravenna user account, not your personal account
• Verify you created a standard user account with a user seat, not an Atlassian Managed Service Account
• Verify the 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

Missing projects or service desks

Cause: Projects not accessible or integration needs refresh

Solution:

• Refresh the integration by disconnecting and reconnecting
• Ensure your Jira site has active projects
• Verify the Ravenna account has access to the projects/service desks
• Check project permissions in Jira admin
• For JSM: Ensure service desk projects are not archived

JSM forms not showing

Cause: Service desk configuration or permissions issue

Solution:

• Verify the service desk has published forms
• Check that forms are not hidden or restricted
• Ensure the Ravenna 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

Permission errors

Cause: OAuth authorization missing required permissions

Solution:

• Verify the OAuth authorization granted all required permissions
• Re-authorize the integration with full permissions
• Check Jira site settings for app restrictions
• Ensure the Ravenna account has appropriate admin/agent access
• Verify account roles in Atlassian Admin

Tickets are being created with no Reporter or Requester

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

Sync interval configuration

Control how frequently Ravenna synchronizes data from your Jira workspace. By default, Ravenna syncs every 5 minutes, but you can adjust this based on your organization’s needs.

1. Navigate to integration settings

   Go to Settings > Integrations and click on your connected Jira integration.

2. Configure sync interval

   In the integration settings, locate the Sync Interval field and enter your desired interval in minutes.

   Recommended intervals:

   • 5 minutes (default): Best for active teams needing near-real-time sync
   • 15 minutes: Good balance for most teams
   • 30-60 minutes: Suitable for less active projects or to reduce API usage
3. Save changes

   Click Save to apply the new sync interval.

The sync interval affects how quickly changes in Jira appear in Ravenna and vice versa. Lower intervals provide faster updates but increase API usage.