> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Jira
> Connect your Jira Cloud site to Serval for two-way ticket syncing, prebuilt workflows, and automation across the full Jira Cloud REST API.
## 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](/sections/integrations/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. Installing the Serval Forge app into your Jira site afterward unlocks ticket syncing and service-account features on Serval-managed connections.
**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
| Capability | Description |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Two-way ticket syncing | Sync tickets between Serval and Jira. Requires a connection made with **Sign in with Jira** plus the Serval Forge app installed in your Jira site; configured in Serval with project, request type, priority mapping, status mapping, and sync strategy. |
| Workflow automation (full Jira Cloud REST API v3) | Serval workflows can call any Jira Cloud REST v3 capability through the proxied Jira API request action, with authentication injected automatically. Service-account and per-user impersonation modes are available per request once the Forge app is installed (Sign in with Jira connections only). |
| Prebuilt workflow: Read Jira Issue Details | Retrieves comprehensive details about a Jira issue by its issue key (e.g., PROJ-123) or issue ID - summary, description, status, assignee, reporter, priority, and other fields. Default approval: installer-approval. |
| Prebuilt workflow: Create Jira Issue | Creates a new Jira issue in a specified project with customizable fields including summary, description, issue type, priority, and assignee. Default approval: installer-approval. |
| Prebuilt workflow: Transition Jira Issue | Moves a Jira issue to a different status (To-Do, In Progress, Done, etc.) - first retrieves the available transitions, then performs the transition. Default approval: installer-approval. |
| Prebuilt workflow: List Jira Projects | Lists all Jira projects the user has access to, including name, key, type, and lead information. Default approval: installer-approval. |
| Jira Service Management catalog-item ingestion | Imports JSM catalog items (request types) as runnable external workflows, including their request form fields, so employees can order them through Serval and each request maps to a workflow run for centralized approvals and audit history. Ships paused by default and activates only when explicitly enabled. |
Anything defined in the [Jira Cloud REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) can be accessed through Serval.
## Get your credentials
There are two ways to connect, and only one of them requires Atlassian-side setup.
No credentials to create. Serval uses its own registered Atlassian app - you only need a Jira account with access to the site you want to connect, and you'll approve the permissions on Atlassian's consent screen. Skip ahead to **Connect in Serval**.
Create an OAuth 2.0 (3LO) integration owned by your Atlassian workspace in the [Atlassian developer console](https://developer.atlassian.com/console/myapps/).
If the Sign in with Jira flow runs into OAuth or consent trouble, connecting with your own app is a dependable way to establish the connection. Ticket syncing still requires a connection made with **Sign in with Jira** plus the Serval Forge app, whichever connect path you use.
The Serval Forge app - required for ticket syncing and service-account features - only attaches to connections made with **Sign in with Jira**. If you need those features, use the Serval-managed option instead.
In the Atlassian developer console, create a new OAuth 2.0 (3LO) integration, or open an existing one.
Under **Permissions**, add the **Jira API** and the **Jira Service Management API** with the same scopes the Serval-managed app requests: `read:jira-user`, `read:jira-work`, `write:jira-work`, `manage:jira-project`, `manage:jira-configuration`, `manage:jira-webhook`, `read:servicedesk-request`, `write:servicedesk-request`, `manage:servicedesk-customer`, and `offline_access`.
Under **Authorization**, paste the **Callback URL** shown in Serval's custom-app setup form into Atlassian's Callback URL field.
The callback URL must match exactly - Atlassian rejects any mismatch. Use the Copy button in the Serval form rather than retyping it.
From the integration's **Settings** page, copy the **Client ID** and the **Secret** (click **Show** next to the secret). You'll paste both into Serval, along with your Jira site subdomain and an optional display name.
## Connect in Serval
This option is badged **Recommended** in the connect modal: "Connect using the Serval-managed Jira integration."
Fill in the **Jira site** field (required) with your subdomain only - the `.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)".
Serval opens Atlassian's authorization screen. Sign in and approve the requested permissions, making sure to select the site that matches the subdomain you entered. (If something unexpected goes wrong before the Atlassian screen opens, the modal shows a generic "Failed to initiate Jira OAuth" message.)
Serval binds the connection to your site automatically. On reconnect, the Jira site field is pre-filled from your existing install.
Modal copy: "Connect with an OAuth 2.0 (3LO) integration owned by your Atlassian workspace."
* **Display name** (optional) - a friendly label shown in Serval; placeholder "My Company Jira". Helper: "A friendly name shown in Serval - you choose this."
* **Jira site** (required) - subdomain only, with the fixed `.atlassian.net` suffix; validated the same way as in the Serval-managed flow.
* **Client ID** (required) - from your integration's Settings page; placeholder "00000000-0000-0000-0000-000000000000". Helper: "Found on the Settings page of your OAuth 2.0 (3LO) integration."
* **Secret** (required) - password field, placeholder "ATOA...". Helper: "Click Show next to the secret on your integration's Settings page to reveal it."
* **Callback URL** - read-only with a Copy button; this is the value you registered in Atlassian.
The submit button stays disabled until all required fields are filled. If an empty value reaches the backend you'll see "clientId is required", "clientSecret is required", or "subdomain is required", surfaced with the prefix "Failed to initiate custom Jira app".
Serval opens Atlassian's authorization screen using your app. Approve the permissions and select the correct site.
Complete the Atlassian approval within **10 minutes** of starting. After that, the connection attempt expires and returns "Invalid or expired OAuth state" - just start again from the form.
Reconnecting a bring-your-own install opens directly in this form with **Display name**, **Client ID**, and **Jira site** pre-filled. The **Secret** is never pre-filled and must be re-entered every time - leaving it blank does not keep the existing secret.
### 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.
In Serval, open the Jira app and turn on **Ticket Syncing**.
Open the [Serval Forge app install page](https://developer.atlassian.com/console/install/c07d3f13-9bca-4772-8bd1-78cb643ba05c?signature=AYABeH3H0ZqUsljeX7xf7cjSBpYAAAADAAdhd3Mta21zAEthcm46YXdzOmttczp1cy13ZXN0LTI6NzA5NTg3ODM1MjQzOmtleS83MDVlZDY3MC1mNTdjLTQxYjUtOWY5Yi1lM2YyZGNjMTQ2ZTcAuAECAQB4IOp8r3eKNYw8z2v%2FEq3%2FfvrZguoGsXpNSaDveR%2FF%2Fo0Buwn9CCqeYgh1%2BEAlr0oGvQAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDGve5jSoRhxnllo%2BiAIBEIA7MzrFlFGrb4Iy5UUirNrX5QJAtKfMDfWNjJ612r2U1%2BTum8UZFPOOU271doEn%2FKZVo911dkk1scv7zhoAB2F3cy1rbXMAS2Fybjphd3M6a21zOmV1LXdlc3QtMTo3MDk1ODc4MzUyNDM6a2V5LzQ2MzBjZTZiLTAwYzMtNGRlMi04NzdiLTYyN2UyMDYwZTVjYwC4AQICAHijmwVTMt6Oj3F%2B0%2B0cVrojrS8yZ9ktpdfDxqPMSIkvHAEKW%2FLX8KhHQrCfkDuzAgjBAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQM52N1SKngCx8hQb%2BzAgEQgDtE%2FmCnfl%2Bz7WbS%2BEkpToi%2F2cFLschi1flQ9Ydmfm7ObPDfBCVxU92e9X8klbTIf5eTKCKUZMOobOLN%2BQAHYXdzLWttcwBLYXJuOmF3czprbXM6dXMtZWFzdC0xOjcwOTU4NzgzNTI0MzprZXkvNmMxMjBiYTAtNGNkNS00OTg1LWI4MmUtNDBhMDQ5NTJjYzU3ALgBAgIAeLKa7Dfn9BgbXaQmJGrkKztjV4vrreTkqr7wGwhqIYs5AacHR7PU7QXKh6Sf2GrPIs8AAAB%2BMHwGCSqGSIb3DQEHBqBvMG0CAQAwaAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAwKMa2VNbko%2FI1kEDMCARCAO9x0vKkBou9b%2BSe4TA%2BPKefH9LSKCelNe2fiYRCaK%2FxDqDItkM9WnCRrnkVKyj8FpJXCs8%2BFpPtvZqdHAgAAAAAMAAAQAAAAAAAAAAAAAAAAALDiZ0DneS2rJV8Ssux8NWv%2F%2F%2F%2F%2FAAAAAQAAAAAAAAAAAAAAAQAAADImSOiACTGK7hIfRop51WUYOsukJB3tlCRlXI4Gvvc2TNQdrdvtYoIiMtFb9105M6i9ksQL4DOzGoC%2BQFImYkSpwjo%3D\&product=jira) on the Atlassian Developer Console and install it into the same Jira site you connected.
The install can take up to five minutes to reflect in Serval. Refresh the Serval page to see the updated status. Installing once upgrades every Sign in with Jira connection to that Jira site across your Serval teams.
In Serval, configure the sync settings: select the project, select the request type, set the priority mapping, set the status mapping, and choose the sync strategy.
## 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."
**List Jira Projects** - validates that the credentials can list projects.
* 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."
**Search Jira Issues** - validates that the credentials can search issues, using a query for issues assigned to the connected user.
* 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."
All three checks can pass while ticket syncing still does nothing - they only exercise the OAuth credentials. If sync isn't working, verify the connection was made with Sign in with Jira, verify the Serval Forge app is installed in the Jira site, and allow up to five minutes after installing it.
## Gotchas and troubleshooting
The connect modal offers exactly two methods: **Sign in with Jira (OAuth)** (Serval-managed, badged Recommended) and **Use your own Atlassian OAuth app**. The Serval Forge app install is a third step that upgrades an existing Sign in with Jira connection - it is required for ticket syncing and service-account features, it is not itself a way to connect, and it does not attach to bring-your-own app connections. (A legacy Jira Connect app path still exists for older installs only; it is deprecated and not offered to new connections.)
After OAuth consent, Serval looks up the subdomain you entered among the sites your Atlassian account authorized. If it isn't there, the connection fails with: "target Jira site '\[subdomain].atlassian.net' not found in accessible resources. Please ensure you have access to this site and selected it during authorization". If no subdomain was given and your account has multiple sites: "multiple Jira sites found (\[number]). Please specify which site to connect by providing the subdomain".
On reconnect, the modal jumps straight to the custom-app form and pre-fills Display name, Client ID, and Jira site - but the Secret is never pre-filled and there is no keep-existing-on-blank behavior. It is required client-side, and the backend rejects an empty value with "clientSecret is required". Have the secret handy (or generate a new one in the Atlassian console) before reconnecting.
The Forge app's credentials are delivered on install and then re-delivered every five minutes, so it may take up to 5 minutes for the installation to take effect. After installing, refresh the Serval page to see the updated status.
Serval requests offline access during authorization specifically so Atlassian returns a refresh token (access tokens expire after about an hour), and refreshes tokens automatically when fewer than 5 minutes of validity remain. If a stored connection somehow lacks a refresh token, calls start failing once the access token expires, with "custom Jira OAuth app access token expired and no refresh token available; reconnect required" - the fix is to reconnect. Also note the connect form's authorization window is 10 minutes; after that you'll see "Invalid or expired OAuth state".
Even with the Forge app installed, Jira calls run as the user who connected the integration unless a workflow opts in: on a Sign in with Jira connection upgraded by the Forge app, sending the `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.
The authoritative OAuth scope list for bring-your-own apps is the 10 scopes shown under **Get your credentials** (9 Jira/JSM scopes plus `offline_access`). 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.
Self-hosted Jira Data Center uses the separate [Jira Data Center](/sections/integrations/jira-data-center) integration and is not covered by this page.
***
Need help? Contact [**support@serval.com**](mailto:support@serval.com) for assistance with your Jira integration.