> ## Documentation Index
> Fetch the complete documentation index at: https://user-docs.olyrosstudios.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira integration

> Connect your Jira Cloud site with a single sign-in and choose which projects Olyros watches.

A company connects one Jira Cloud site by OAuth. Olyros registers a webhook on the
projects the company chooses, offers every issue event to the company's
[workflows](https://user-docs.olyrosstudios.com/workflows.md), and lets workflows and [schedules](https://user-docs.olyrosstudios.com/schedules.md) create,
comment on, label and transition issues. The connection lives under **Settings ->
Integrations** (`/integrations`), then the Jira connection
(`/integrations/jira/:connectionId` with **Status** (`status`), **Projects** (`projects`),
**Webhooks** (`webhooks`) and **Settings** (`settings`) tabs). Jira has no GraphQL surface; everything is REST under `/api/jira`.

## What it does

* **Connect by OAuth 2.0 (3LO).** `GET /api/jira/connect` stages a single-use state
  (10 minutes) and starts Atlassian consent; `GET /api/jira/callback` redeems it,
  re-checks that the initiator is still a member, exchanges the code, picks the accessible site and stores a
  `JiraConnection` (cloud id, site URL and name, scopes, encrypted access and refresh
  tokens). Access tokens are refreshed proactively five minutes before expiry. Status is
  `active`, `token_expired`, `error` or `disconnected`; one connection per site per
  company (`uq_jira_conn_company_cloud`).
* **Register the webhook.** `POST /api/jira/connections/{connection_id}/webhooks`
  registers a dynamic webhook for `jira:issue_created`, `jira:issue_updated` and
  `jira:issue_deleted` scoped by `monitored_projects`, with a per-connection callback
  token in the URL. Atlassian webhooks expire after 30 days; Olyros refreshes them
  (`refresh_webhook`) and can purge stale registrations.
* **Receive events safely.** `POST /api/jira/webhooks/{token}`: the token hash selects
  the connection and its company (only `active` connections; an unknown or inactive
  token gets a plain 404); each connection is held to 120 requests per rolling minute
  (429 beyond); the body is capped at the platform's maximum payload size; when the
  platform's Jira app secret is configured the `x-hub-signature` is verified; the body is deduplicated for seven days (`JiraWebhookDelivery`:
  `claimed`, `processed`, `failed`); events for projects outside `monitored_projects`
  are dropped. Deliveries are listed at `GET .../webhook-events`. Only the per-connection
  URL with its token accepts deliveries; a webhook registered on a connection before the
  token was introduced must be registered again.
* **Start workflows.** Each accepted event is offered to active workflows whose
  `jira_event` trigger names this connection with the matching event type
  (`status_change`, `issue_created`, `label_added` on added labels only, or
  `issue_deleted`); `jira_filter` nodes then narrow
  on `status_to`, labels and other flattened fields.
* **Act on issues.** Workflow nodes `create_jira_ticket` (project, issue type,
  summary, description, priority, labels) and `jira_update` (`transition`,
  `comment`, `add_label`, `remove_label`); the adapter also supports
  transition-to-done and status lookups. Comments are written as Atlassian Document
  Format.
* **Metadata for forms.** Projects, issue types and statuses per project
  (`GET /api/jira/connections/{connection_id}/projects`, `.../issue-types`,
  `.../statuses`) feed the node configuration UI; `fetch-issue` wraps a real issue as a
  synthetic webhook payload for the workflow canvas Test tab.
* **Scheduled issues carry front matter.** When a schedule creates a Jira issue "for an
  agent", the description starts with a YAML front matter block (agent, schedule id,
  repositories). There is no per-connection trigger setting: Jira events reach agents
  only through workflows with a JIRA Event (`jira_event`) trigger on the connection.
* **Platform side.** The Atlassian OAuth app (client id and secret, webhook secret) is
  configured once in the admin app (`/integrations/jira`, `/api/admin/jira/config`).

## Who can use it

* Connect (`GET /api/jira/connect`), verify, disconnect and register webhooks
  (choosing monitored projects): **editor or admin** (ability `integration.manage`,
  listed under **Settings -> Roles**, `/settings/roles`). A viewer gets 403
  `EDITOR_REQUIRED`; the page shows "Only editors and admins can change this
  integration." next to the action.
* List connections, browse projects, issue types and statuses, fetch an issue
  for the Test tab, view deliveries: **any company member**.
* Platform Jira app configuration: **platform admin**.
* No plan or tier gate.

## How to configure it

1. A platform admin sets the Atlassian app credentials once (`PUT /api/admin/jira/config`).
2. Settings -> Integrations (`/integrations`) -> Jira -> Connect (`/api/jira/connect`),
   approve at Atlassian within ten minutes; you return to the connection's Status tab.
3. **Projects** tab: choose the monitored projects and register the webhook
   (`POST /api/jira/connections/{connection_id}/webhooks`).
4. To have Jira events reach an agent, build a workflow with a JIRA Event
   (`jira_event`) trigger on this connection, for example `jira_event` ->
   `create_task` -> `dispatch_task`; use the **Test** tab's "fetch issue" to try it
   with real data.
5. `POST .../verify` checks the token and site; `DELETE /api/jira/connections/{id}`
   disconnects (and marks open issue links as errored).

## Limits and defaults

| Setting | Default | Where enforced |
| - | - | - |
| Connections | one per Jira site per company | unique constraint |
| Webhook events | `jira:issue_created`, `jira:issue_updated`, `jira:issue_deleted` | webhook registration |
| Webhook lifetime | 30 days, refreshed by Olyros | `refresh_webhook` |
| Token refresh | 5 minutes before expiry | `get_access_token` |
| Delivery dedup | SHA-256 of connection id + body, kept 7 days; stale `claimed` rows re-claimable after 15 minutes | `JiraWebhookDelivery` |
| Monitored projects | none configured = all projects accepted | webhook handler |
| Signature check | only when the platform app secret is set | webhook ingress |
| Webhook rate | 120 requests per connection per rolling minute, per server instance | `JIRA_WEBHOOK_RATE_LIMIT_PER_MINUTE` |
| Webhook body size | platform maximum payload setting | webhook ingress |
| Connect link lifetime | 10 minutes, single use | link state |
| Scheduled issue format | YAML front matter, always | schedule trigger |

## What it emits

* Workflow runs for matched events; webhook delivery and dedup records.
* Issues, comments, labels and transitions in Jira created by workflow nodes or
  schedules.
* `last_webhook_at`, `last_error` and status on the connection.

## Known gaps

* A Jira issue never becomes a task by itself: the webhook handler only starts
  workflows. The GitHub integration turns labelled issues into tasks directly; Jira
  needs a workflow with `jira_event` -> `create_task` -> `dispatch_task`. Scheduled
  Jira issues "for an agent" therefore have no consumer unless such a workflow exists.
* No issue search (JQL) in the adapter, so duplicates cannot be detected before
  `create_jira_ticket`.
* No Jira Data Center or Server support; Cloud only.
* Cloud tasks have no Jira access of their own; only server-side workflow nodes use the
  connection's token.

## Customer-safe summary

Connect your Jira Cloud site with a single sign-in and choose which projects Olyros
watches. Issue creation, status changes and label changes in those projects can start
your automations, and automations can create issues, comment, add labels and move
issues between statuses. Olyros keeps the connection healthy by refreshing the
credentials and the webhook on its own, and shows you every event it received.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.