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

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

Open the Serval Forge app install page on the Atlassian Developer Console and install it into the same Jira site you connected.

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.

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)

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

Verifying the connection

Gotchas and troubleshooting