Skip to main content

​
About Jira Data Center

The Jira Data Center integration connects Serval to a Jira instance you host yourself. It is a separate integration from Jira (Cloud): it talks directly to your own host and authenticates with an API token you provide instead of OAuth. This version (marked Beta in the connect UI) gives workflows and Catalyst typed access to your instance’s API plus a connection health check - there are no prebuilt Jira workflows, no two-way ticket sync, and no Jira Service Management support yet. If your Jira lives at yourcompany.atlassian.net, use the Jira (Cloud) integration instead. Authentication: API token. You supply your instance’s Base URL and a personal access token; Serval stores the token securely server-side and attaches it to every request on your behalf, so workflows never see the raw token. Basic auth (username plus password) is not supported. Data sync: On-demand only. There is no background sync - Serval does not sync tickets, ingest catalog entities, or poll your instance on a schedule. It calls your Jira Data Center host only when a workflow, Catalyst session, or connection health check runs.

​
What the Jira Data Center integration enables

CapabilityDescription
Typed API requestsA “Jira Data Center API request” action covering 283 endpoints, spanning the Jira platform REST API (version 2) and the Jira Agile API - issues, projects, users, workflows, permissions, agile boards, sprints, backlog, epics, and more. Workflows and Catalyst can do anything the connected token is permitted to do.
Catalyst workflow authoringServal’s AI knows the Jira Data Center API, so Catalyst can discover the right endpoints and build working Data Center workflows for you.
Connection health checkVerifies your stored Base URL and token by looking up the account the token belongs to, and reports who the integration is connected as.
Anything defined in the Jira Data Center API can be accessed through Serval.

​
Get your credentials

Serval acts with the permissions of the token you connect, so create the token as the user whose access Serval should have. There are two ways to get a token, depending on how your instance is set up.
Use a dedicated service account to create the token. That keeps Serval’s access independent of any one person’s account and makes the token’s permissions easy to audit.
On Jira 8.14 and later, use a built-in Jira personal access token. Atlassian’s guide is Using Personal Access Tokens.
1

Open your profile

In Jira, select your avatar at the top right of the screen, then select Profile.
2

Go to Personal access tokens

Select Personal access tokens in the left-hand menu.
3

Create the token

Select Create token and give it a name. You can optionally set an expiry - if you do, plan to rotate the token in Serval before it expires.
4

Copy the token

Copy the token immediately - Jira shows it only once.
Atlassian also documents personal access tokens in more depth in its developer guide.

​
Connect in Serval

1

Select Jira Data Center

In Serval, open your team’s integrations page and select Jira Data Center. The integration is marked Beta.
2

Enter the Base URL (required)

Enter your instance’s address, for example https://jira.example.com. The helper text reads: The base URL of your self-hosted Jira Data Center instance (e.g. https://jira.acme.com).You can paste the full address from your browser - Serval keeps only the host part, removing the https:// prefix and anything after the host, while a port is kept (entering https://jira.example.com:8443/ stores jira.example.com:8443). Submitting the field empty is rejected with “Base URL is required”; a value Serval cannot read as a host is rejected with “Base URL must be a valid Jira host, e.g. https://jira.example.com”.
3

Enter the API Token (required)

Paste the token you created. This is a password field, and its helper text reads: A personal API token. If your instance uses the Resolution “API Token Authentication” app, generate one from your profile’s “My API Tokens” page. Native Jira personal access tokens also work here and are the first-party path on Jira 8.14 and later. Submitting the field empty is rejected with “API Token is required”.
4

Submit and let the health check run

Submit the form. Serval saves the connection and automatically runs the connection health check.
When editing an existing connection, the Base URL field comes pre-filled with the stored host, and the API Token field shows a masked placeholder (bullet characters plus the last 4 characters of the stored token) behind a replace control. Leaving the token untouched or blank keeps the stored token, and leaving Base URL blank keeps the stored host - you only need to fill in the field you are rotating.

​
Verifying the connection

The integration has one health check, Validate Jira Data Center API Connection. It runs automatically when you connect and again when you save credential changes, and you can re-run it any time from the integration’s settings page. It confirms that Serval can reach your instance at the stored Base URL and sign in with the stored token by looking up the account the token belongs to.
  • On success: “Successfully connected to Jira Data Center as [name].” - [name] is the account’s display name, or its username if no display name is set. If your instance returns neither, it shows “Successfully connected to Jira Data Center.” instead.
  • On failure: “Unable to connect to Jira Data Center. Please verify your base URL and API token are correct.”
If the health check passes but a workflow step fails, the token is usually the issue, not the connection. The health check only verifies sign-in - it does not check Jira permissions. Make sure the account the token belongs to has permission in Jira for the projects and actions your workflow touches.

​
Gotchas and troubleshooting

This integration is for self-hosted Jira Data Center. If your Jira lives at yourcompany.atlassian.net, use the Jira (Cloud) integration instead - it has OAuth, prebuilt workflows, and two-way ticket sync that this integration does not. The two are not interchangeable.
Serval always connects to your configured host over HTTPS, so the instance must serve TLS - one that only speaks plain HTTP will not work. Serval also blocks requests to hosts that resolve to internal or private IP addresses, so an instance reachable only on a private network cannot be connected and the health check will fail even with a valid token. Expose the instance on a publicly resolvable HTTPS address and allow inbound access from Serval before connecting.
Serval stores only the host portion of your Base URL - any path is removed. If Jira is mounted under a path on a shared host (for example, https://apps.example.com/jira), Serval’s requests will go to the wrong address and fail. Your instance must serve Jira at the root of its host. Ports are fine: https://jira.example.com:8443 is stored as jira.example.com:8443.
Serval sends the token as a Bearer authorization header. Native Jira personal access tokens (Jira 8.14 and later) support this out of the box. Tokens from the Resolution “API Token Authentication” app accept it only from app version 1.7.0 onward - older app versions require basic authentication, which this integration does not support.
This version provides typed API access for custom workflows and Catalyst, plus the connection health check. It does not include prebuilt workflows (such as create issue, transition issue, or list projects), ticket sync, catalog or entity ingestion, or Jira Service Management support. The integration is marked Beta in the connect UI.
Data Center exposes version 2 of the Jira REST API, while Cloud workflows are typically built against version 3, and issue search works differently on Data Center (a different search call with page-by-page offsets). Workflows written against the Cloud Jira integration will not run unmodified - rebuild them against this integration, or ask Catalyst to, and the correct Data Center endpoints will be used.
When editing the connection, the Base URL field comes pre-filled with the stored host, and the API Token field shows a masked bullets-plus-last-4 placeholder behind a replace control. Leaving the token untouched or blank keeps the stored token, and leaving Base URL blank keeps the stored host. Fill in only the field you are rotating.
Need help? Contact support@serval.com for assistance with your Jira Data Center integration.