About Jira
The Jira integration connects a Jira Cloud site (yourcompany.atlassian.net) to Serval. Once connected, Serval can sync tickets two-way between Serval and Jira, run prebuilt Jira workflows, and automate anything the Jira Cloud REST API supports - with authentication handled for you. Self-hosted Jira Data Center uses a separate integration and is not covered on this page.
Authentication: Atlassian OAuth 2.0 (3LO) - either Serval-managed sign-in (recommended) or your own Atlassian OAuth app. Both paths use the same permission picker, so you choose exactly which Jira scopes the connection requests. Installing the Serval Forge app into your Jira site afterward unlocks ticket syncing and service-account features on connections made with either method.
Data sync: Two-way ticket syncing runs in the background once the Forge app is installed and sync settings are configured; workflow actions run on demand. Access tokens are refreshed automatically for both connection methods.
What the Jira integration enables
Get your credentials
There are two ways to connect, and only one of them requires Atlassian-side setup.- Sign in with Jira (Recommended)
- Use your own Atlassian OAuth app
Connect in Serval
- Sign in with Jira (OAuth)
- Use your own Atlassian OAuth app
Enter your Jira site
.atlassian.net suffix is fixed next to the input. Helper text: “For example, if your Jira URL is acme.atlassian.net, enter acme.” Leaving it empty shows “Jira subdomain is required”; anything other than letters, numbers, and hyphens - or a value that starts or ends with a hyphen - shows “Please enter a valid subdomain (letters, numbers, and hyphens only)”.Choose Permission Presets (required)
Approve on Atlassian
Done
Install the Serval Forge app (required for ticket syncing)
Order matters: connect with Sign in with Jira first, then install the Forge app. The Forge app upgrades your existing Serval-managed OAuth connection with service-account capabilities - it is not a standalone way to connect, but ticket syncing won’t work without it. Connections made with your own Atlassian OAuth app are not upgraded by the Forge app; reconnect with Sign in with Jira if you need ticket syncing.Turn on ticket syncing
Install the app into your Jira site
app.eu1.serval.com must use the EU app — the US app sends lifecycle webhooks to the US shard only.- United States (US1)
- European Union (EU1)
Wait for it to take effect
Configure ticket syncing
How ticket sync behaves
- Sync Out: tickets created in Serval are sent to Jira. Jira issues aren’t imported.
- Sync In: Jira issues are imported into Serval. Tickets created in Serval aren’t automatically sent to Jira.
- Two-way Sync: tickets created in Serval are sent to Jira, and Jira issues are imported into Serval.
Mirror your Jira workflow as a Request state machine
In the Jira ticket-source setup, the Request State Machine step can import your synced project’s Jira workflow (its statuses and transitions) into Serval’s native status transition rules for the Request ticket type. Map every Jira status first, then turn on Enforce status transitions to build the state machine from Jira. Once enforced, Requests move only between connected statuses, for both people and Serval AI, matching your Jira workflow. Use Rebuild from Jira to re-import after the Jira workflow changes, and edit the result anytime under Settings → Ticket types for the Request type. Turning enforcement off lets Requests move between any statuses again.Verifying the connection
Serval runs three health checks against the connection: Test Jira Connection - validates basic connectivity and authentication by looking up the connected user.- Success: “Successfully authenticated with Jira as [name]” (shows “user” when no display name is available)
- Failure: “Unable to authenticate with Jira. Please verify your API credentials and permissions are correct.”
- Success: “Successfully listed projects from Jira (sample size: [number])”
- Failure: “Unable to list projects from Jira. Please verify your API credentials have permission to browse projects.”
- Success: “Successfully searched issues in Jira (found: [number])”
- Failure: “Unable to search issues in Jira. Please verify your API credentials have permission to search and read issues.”
Gotchas and troubleshooting
Two connect options, plus a separate Forge app install for ticket syncing
Two connect options, plus a separate Forge app install for ticket syncing
Reconnecting a bring-your-own app always requires re-entering the Secret
Reconnecting a bring-your-own app always requires re-entering the Secret
Forge app install can take up to ~5 minutes to show in Serval
Forge app install can take up to ~5 minutes to show in Serval
Bring-your-own refresh tokens: automatic, but unrecoverable if absent
Bring-your-own refresh tokens: automatic, but unrecoverable if absent
Requests default to the connecting user's identity
Requests default to the connecting user's identity
X-Use-Connect-Auth: true header switches to the Forge service account, and X-As-Jira-User additionally impersonates a specific Jira account. The opt-in header is harmless on connections without the Forge app, including bring-your-own app connections.Adding or changing permissions later requires reconnecting
Adding or changing permissions later requires reconnecting
Ticket sync configuration needs manage:jira-configuration
Ticket sync configuration needs manage:jira-configuration
manage:jira-configuration scope: per-project priority schemes (the priority-mapping picker falls back to the site-wide priority list without it, which can offer options a project’s scheme rejects on sync) and the project workflow graph (the Request State Machine’s import fails without it). These reads always run with the connection’s own token - they do not use the Forge app’s service account - so installing the Forge app does not stand in for the scope. When the connection’s granted scopes lack manage:jira-configuration, the Priority Mapping step shows a warning and the Request State Machine step blocks building or rebuilding (turning an existing state machine off stays possible); reconnect with the Projects & Administration preset selected to clear it.Use the scope list on this page when mirroring permissions
Use the scope list on this page when mirroring permissions
offline_access). Serval requests the subset you select in the picker, but granting the full set on the Atlassian app keeps every selection available. The scopes read:form:jira and read:form.field:jira belong only to the Serval Forge app - do not add them to your OAuth app expecting them to be requested.Jira Data Center is a separate integration
Jira Data Center is a separate integration
Need help? Contact support@serval.com for assistance with your Jira integration.

