Jira - Serval Documentation

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. 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

Capability	Description
Two-way ticket syncing	Sync tickets between Serval and Jira, configured in Serval with project, request type, priority mapping, status mapping, and sync strategy. Works with either connection method: Sign in with Jira connections must have the Serval Forge app installed, while your-own-OAuth-app connections can sync without it (installing Forge is recommended so tickets and comments are attributed to their real creators).
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 Serval Forge app is installed.
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 can be accessed through Serval.

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

Create an OAuth 2.0 (3LO) integration owned by your Atlassian workspace in the Atlassian developer console.

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. Your-own-app connections support ticket syncing too - installing the Serval Forge app is recommended so tickets and comments are attributed to their real creators.

The Serval Forge app attaches to your-own-OAuth-app connections as well as Serval-managed ones. On a your-own-app connection it is recommended but not required - ticket syncing works without it, and installing it improves ticket and comment attribution and unlocks service-account and per-user impersonation. Connections made with Sign in with Jira still require the Forge app before ticket sync can be configured.

Create or open an integration

In the Atlassian developer console, create a new OAuth 2.0 (3LO) integration, or open an existing one.

Add API permissions

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.

Copy the Client ID and Secret

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

Sign in with Jira (OAuth)
Use your own Atlassian OAuth app

This option is badged Recommended in the connect modal: “Connect using the Serval-managed Jira integration.”

Enter your Jira site

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)”.

Approve on Atlassian

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.)

Done

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.”

Fill in the form

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”.

Approve on Atlassian

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 later

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.

Turn on ticket syncing

In Serval, open the Jira app and turn on Ticket Syncing.

Install the app into your Jira site

Install the regional Forge app for your Serval deployment. EU customers on 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)

Open the US Serval Forge app install page and install it into the same Jira site you connected.

From the Jira ticket-syncing setup in Serval (app.eu1.serval.com), follow the Atlassian app installation page link. That link targets the EU Forge app, which sends install and token-refresh webhooks to the EU1 backend.

Wait for it to take effect

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.

Configure ticket syncing

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.

How ticket sync behaves

Assignees. When an AI-owned Jira issue — for example, a catalog-workflow request Serval created — escalates and syncs out, Serval assigns the issue to its own app account by default. On Jira sources that sync out on escalation, turn on Leave AI-owned tickets unassigned to leave those issues unassigned in Jira instead. Human assignments still sync out as normal, and enabling the setting never strips an assignee a person picked up in Jira. Attachments. A file synced from Jira lands on the same Serval message as the comment it was attached to. A file added to an internal Jira comment therefore stays an internal note in Serval rather than surfacing as a public timeline message, so it isn’t echoed onto customer-visible or cross-channel threads.

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.”

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

Two connect options, plus a separate Forge app install for ticket syncing

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.)

The subdomain must match a site you authorized

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”.

Reconnecting a bring-your-own app always requires re-entering the Secret

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.

Forge app install can take up to ~5 minutes to show in Serval

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.

Bring-your-own refresh tokens: automatic, but unrecoverable if absent

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”.

Requests default to the connecting user's identity

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.

Use the scope list on this page when mirroring permissions

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.

Jira Data Center is a separate integration

Self-hosted Jira Data Center uses the separate Jira Data Center integration and is not covered by this page.

Need help? Contact support@serval.com for assistance with your Jira integration.

​About Jira

​What the Jira integration enables

​Get your credentials

​Connect in Serval

​Install the Serval Forge app (required for ticket syncing)

​How ticket sync behaves

​Mirror your Jira workflow as a Request state machine

​Verifying the connection

​Gotchas and troubleshooting

About Jira

What the Jira integration enables

Get your credentials

Connect in Serval

Install the Serval Forge app (required for ticket syncing)

How ticket sync behaves

Mirror your Jira workflow as a Request state machine

Verifying the connection

Gotchas and troubleshooting