# Jira (API Token) — Issue Tracking API: connection

> Canonical URL: https://developers.apideck.com/apis/issue-tracking/jira-api-token/connection

# How to Connect to Jira (API Token)

This guide will help you connect your Jira Cloud site to Apideck's Unified API using a **service account**, an Atlassian email address and API token, instead of OAuth 2.0. This is the recommended option for enterprise integrations that cannot be tied to a named human user.

## Prerequisites

Before you begin, make sure you have:

- An active Atlassian account (ideally a dedicated service account) with access to the Jira project(s) you want to integrate
- Permission to read issues, projects, and users; and, if you will create or update issues via Apideck, write access
- Your Jira **Cloud ID**

## How to Get Credentials

### Step 1: Get Your Email

Use the email address of the Atlassian account that will own the connection. This is the email you use to log in at [id.atlassian.com](https://id.atlassian.com). For enterprise setups, use a dedicated service-account email rather than a personal one.

### Step 2: Generate an API Token

1. Go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API token**
3. Enter a label (e.g., "Apideck Integration") and click **Create**
4. Copy the generated token immediately: it will not be shown again

> **Token expiry:** Atlassian scoped API tokens expire between 1 and 365 days (default: 1 year). There is **no automatic refresh** for this connection type: when the token expires, the connection will stop authenticating and you must generate a new token and update it in Apideck Vault.

### Step 3: Find Your Cloud ID

Your Cloud ID identifies your Jira site. Use either method below:

**Method 1: `_edge/tenant_info` (recommended):**

1. Log in to your Jira site in a browser.
2. In the same browser, visit `https://<your-site>.atlassian.net/_edge/tenant_info` (replace `<your-site>` with your site's subdomain).
3. The page returns JSON like `{"cloudId":"fff89a1a-52c8-11e5-91b2-3c15c2bd8caa"}`. Copy the `cloudId` value.

**Method 2: Atlassian admin console:**

1. Go to [admin.atlassian.com](https://admin.atlassian.com) and select your site.
2. Look at the URL. Your Cloud ID is the value in the `/s/<cloud-id>/` segment: for example, in `https://admin.atlassian.com/s/fff89a1a-52c8-11e5-91b2-3c15c2bd8caa/users`, the Cloud ID is `fff89a1a-52c8-11e5-91b2-3c15c2bd8caa`.
3. **Do not** use the `/o/<org-id>/` segment: that is your **Organization ID**, a different value that will not work here.

> For more detail, see Atlassian's guide: [Retrieve my Atlassian site's Cloud ID](https://support.atlassian.com/jira/kb/retrieve-my-atlassian-sites-cloud-id/).

## Configure in Apideck

### Step 1: Enter Your Credentials

In Apideck Vault, enter the following settings:

- **Email**: The Atlassian account email address
- **API Token**: The API token generated in Step 2
- **Cloud ID**: The Cloud ID found in Step 3

### Step 2: Save the Connection

Click **Save**. Apideck validates the connection by listing your Jira projects. If the email, API token, and Cloud ID are all correct, the connection becomes active.

> **Tip:** A common cause of failure is a typo in the **Cloud ID**: it must be the exact site identifier, not your site subdomain.

## Troubleshooting

### 401 Unauthorized

If you receive a 401 error:

- Verify the email address matches the Atlassian account that generated the token
- Check that the API token is valid and has not expired or been revoked
- Ensure you copied the full API token without extra spaces

### 404 Not Found / empty results

If requests return 404 or no data:

- Confirm the **Cloud ID** is correct (see Step 3): a wrong Cloud ID points requests at the wrong or a non-existent site
- Ensure the service account has access to the Jira project(s) you are querying

### 403 Forbidden

If you receive a 403 error:

- Confirm the service account has the required permissions (read issues/projects/users; write for creating or updating issues)

## Additional Resources

- [Atlassian: Manage API tokens for service accounts](https://support.atlassian.com/user-management/docs/manage-api-tokens-for-service-accounts/)
- [Atlassian: Basic auth for REST APIs](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/)


[API reference](https://developers.apideck.com/apis/issue-tracking/reference.md) · [Coverage matrix](https://developers.apideck.com/apis/issue-tracking/coverage)