> ## 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 Data Center

> Connect Serval to your self-hosted Jira Data Center instance with an API token so workflows and Catalyst can call its API on demand.

## 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)](/sections/integrations/jira): 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](/sections/integrations/jira) 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

| Capability                  | Description                                                                                                                                                                                                                                                                                                               |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Typed API requests          | A "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 authoring | Serval'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 check     | Verifies 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](https://docs.atlassian.com/software/jira/docs/api/REST/latest/) 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.

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

<Tabs>
  <Tab title="Native personal access token (Jira 8.14 and later)">
    On Jira 8.14 and later, use a built-in Jira personal access token. Atlassian's guide is [Using Personal Access Tokens](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).

    <Steps>
      <Step title="Open your profile">
        In Jira, select your avatar at the top right of the screen, then select **Profile**.
      </Step>

      <Step title="Go to Personal access tokens">
        Select **Personal access tokens** in the left-hand menu.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Copy the token">
        Copy the token immediately - Jira shows it only once.
      </Step>
    </Steps>

    <Note>
      Atlassian also documents personal access tokens in more depth in its [developer guide](https://developer.atlassian.com/server/jira/platform/personal-access-token/).
    </Note>
  </Tab>

  <Tab title="Resolution API Token Authentication app">
    If your instance uses the Resolution "API Token Authentication" Marketplace app instead of native tokens:

    <Steps>
      <Step title="Open the token page">
        Click your profile icon and open the **API Token Authentication** link.
      </Step>

      <Step title="Create the token">
        Create a token on the **My API Tokens** tab. See the [Resolution user guide](https://wiki.resolution.de/doc/api-token-authentication/latest/user-guide) for details.
      </Step>
    </Steps>

    <Warning>
      Tokens from the Resolution app work with Serval only from app version **1.7.0** onward. Older app versions require basic authentication, which this integration does not support.
    </Warning>
  </Tab>
</Tabs>

## Connect in Serval

<Steps>
  <Step title="Select Jira Data Center">
    In Serval, open your team's integrations page and select **Jira Data Center**. The integration is marked **Beta**.
  </Step>

  <Step title="Enter the Base URL (required)">
    Enter your instance's address, for example [https://jira.example.com](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](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/](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](https://jira.example.com)".
  </Step>

  <Step title="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".
  </Step>

  <Step title="Submit and let the health check run">
    Submit the form. Serval saves the connection and automatically runs the connection health check.
  </Step>
</Steps>

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

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

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

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Data Center only - Cloud uses a different integration">
    This integration is for self-hosted Jira Data Center. If your Jira lives at yourcompany.atlassian.net, use the [Jira (Cloud) integration](/sections/integrations/jira) instead - it has OAuth, prebuilt workflows, and two-way ticket sync that this integration does not. The two are not interchangeable.
  </Accordion>

  <Accordion title="Your instance must be reachable over public HTTPS">
    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.
  </Accordion>

  <Accordion title="Context-path deployments are not supported">
    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](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](https://jira.example.com:8443) is stored as jira.example.com:8443.
  </Accordion>

  <Accordion title="The token must support Bearer authentication">
    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.
  </Accordion>

  <Accordion title="v1 scope: API access only">
    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.
  </Accordion>

  <Accordion title="Porting Cloud workflows needs changes">
    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.
  </Accordion>

  <Accordion title="Updating credentials keeps existing values on blank">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Jira Data Center integration.