JIRA API token

InsightWorker's jira_search and jira_issue tools authenticate to Atlassian Cloud via HTTP Basic auth (your email + an API token).

Step 1 — Get the API token

Visit id.atlassian.com/manage-profile/security/api-tokens
Click Create API token
Label it insightworker so you can find it later
Copy the token immediately — Atlassian shows it once

Step 2 — Configure InsightWorker

~/.insightworker/.env:

JIRA_BASE_URL=https://yourorg.atlassian.net
JIRA_EMAIL=you@yourorg.com
JIRA_API_TOKEN=<the token from step 1>

JIRA_BASE_URL should NOT have a trailing slash. Use the bare hostname your team types into a browser.

Restart the agent.

Step 3 — Verify

In the chat:

List my open JIRA issues from the active sprint.

Should return ticket keys + summaries. If you get 401 Unauthorized, double-check that JIRA_EMAIL is the email associated with your Atlassian account (not your tenant's Slack-linked alias or anything similar).

Permissions

API tokens inherit the permissions of the user who created them. The user needs read access to the projects and issues you intend to query. For most teams this is the default — if you can search for it in the JIRA UI, the token can search for it via API.

For agent apps that update issues (add comments, transition statuses), the token user needs the corresponding write permissions. We currently only ship read tools (jira_search, jira_issue); write capability is on the roadmap.

Self-hosted JIRA Server / Data Center

The token flow above is Atlassian Cloud only. Self-hosted JIRA Server / Data Center uses Personal Access Tokens via a different endpoint. Set:

JIRA_BASE_URL=https://jira.yourcompany.com
JIRA_EMAIL=  # leave blank
JIRA_API_TOKEN=<personal access token from your JIRA profile>

The agent's jira_search will route correctly when JIRA_EMAIL is empty (uses Bearer auth instead of Basic).

Rotation

Tokens don't auto-expire on Atlassian Cloud unless your org has a policy. Best practice is to rotate every ~90 days:

Create a new token in the Atlassian UI
Update JIRA_API_TOKEN in .env
Restart the agent
Delete the old token

Common gotchas

Symptom	Cause	Fix
`401 Unauthorized`	Email / token mismatch	Verify `JIRA_EMAIL` matches the Atlassian account that issued the token
`403 Forbidden` on a project	Permission scheme	Token user needs Browse Projects on the target project
`JQL parse error`	Bad JQL syntax	Run the same JQL in JIRA's UI search to validate; agent passes it through unchanged
Empty results when issues exist	Wrong project filter	Many JQL queries default to "active sprint of current board"; specify project explicitly: `project = ENG AND ...`