> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/integrations/jira.md).

# Jira

The Jira driver validates the configured identity through Jira's `myself` endpoint. It records the account ID, display name, and active state. Use either OAuth or email/API-token authentication.

## Required values

| Authentication      | Configuration       | Secret         |
| ------------------- | ------------------- | -------------- |
| OAuth               | `site_url`          | `access_token` |
| Atlassian API token | `site_url`, `email` | `api_token`    |

Example site URL: `https://acme.atlassian.net`.

## Provider preparation

1. Choose OAuth for managed authorization or create an Atlassian API token.
2. Use a dedicated account with the minimum Jira access required by your policy.
3. Confirm the account is active and not blocked by organization policy.

## Configure through the Admin Integration API

Use an `admin` or `super_admin` bearer token and select the target tenant for the catalog, installation, and manual-sync requests:

```bash
export KANGAL_URL='https://kangal.example.com'
export KANGAL_ADMIN_TOKEN='kangaladm_...'
export KANGAL_TENANT_ID='tenant-acme'

curl -fsS \
  -H "Authorization: Bearer $KANGAL_ADMIN_TOKEN" \
  "$KANGAL_URL/api/v1/admin/integrations?tenant_id=$KANGAL_TENANT_ID" \
  | jq '.items[] | select(.definition.slug == "jira")'
```

Install Jira with email/API-token authentication:

```bash
curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/integrations" \
  -d '{
    "slug": "jira",
    "tenant_id": "tenant-acme",
    "config": {
      "site_url": "https://acme.atlassian.net",
      "email": "jira-sync@acme.example"
    },
    "secrets": {
      "api_token": "REDACTED"
    }
  }' | jq
```

For OAuth, omit `config.email` and send `secrets.access_token` instead of `secrets.api_token`. The installation request accepts either inline `secrets` or a Jira-scoped `secrets_ref`, but not both.

Copy `installation.id` from the create response and run a manual sync:

```bash
export JIRA_INSTALLATION_ID='installation-id-from-create-response'

curl -fsS -X POST \
  -H "Authorization: Bearer $KANGAL_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  "$KANGAL_URL/api/v1/admin/integrations/$JIRA_INSTALLATION_ID/sync?tenant_id=$KANGAL_TENANT_ID" \
  -d '{"reason":"Verify Jira access"}' | jq
```

Installation validates the common request envelope, tenant scope, and secret source. The worker validates Jira's required fields and provider connectivity when it runs the manual sync.

## Common failures

* **401:** the email/token pair or OAuth token is invalid.
* **403:** the identity is blocked by Jira or organization policy.
* **404:** the site URL is incorrect.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/integrations/jira.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.