Integrating to JIRA

​

Prerequisites

• A Katilyst API key. An Account Admin generates one from the Admin Portal. Have it in hand before you start (keys are shown once when generated, and a lost key cannot be recovered.)
• Permission to create automation rules in the JIRA space you are working in.
• A decision on the three mappings below.

​

Decide your three mappings

​

Configure the action in Katilyst

curl https://api.katilyst.com/v1/projects \
  -H "Authorization: API-Key your_key_here"

curl https://api.katilyst.com/v1/projects/{projectId}/available-actions \
  -H "Authorization: API-Key your_key_here"

​

Build the automation rule

1

Create the rule

In the JIRA space holding your security work, go to Space settings → Automation → Create rule. Older Jira versions label this Project settings.

2

Set the trigger

Choose Work item transitioned, and set the destination to the status that means the work is finished in your workflow.In the worked example that is Done. Your workflow may use Resolved, Closed, Remediated, or a status specific to your security process. If more than one status counts as finished, list them all — the trigger accepts several.

If your workflow sets a resolution rather than moving to a distinct status, Work item resolved is the cleaner trigger and saves you maintaining a list of statuses.

3

Set the conditions

Conditions are where you control what counts. Without them, every completed work item of any kind earns credit.You need enough conditions to isolate security work and to confirm there is someone to credit. In the worked example that is a pair:

• Work item type is Vulnerability
• The Security Champion field is not empty

Your equivalent might instead be a Bug carrying a security label, anything in a particular component, or every item in a dedicated security space. Match whatever your teams already do rather than asking them to change for this rule — an automation that depends on a new convention stops working the moment someone forgets it.Add a condition confirming the field you are crediting is populated, whichever field that is. It costs nothing and it prevents calls that fail validation.

Frequency limits configured on an Available Action do not apply to actions logged through the API, so your conditions are the only thing limiting how often this rule awards credit. A bulk transition closing fifty tickets at once will log fifty actions. If that is a realistic scenario in your workflow, constrain the rule here rather than relying on the limit set in Katilyst.

4

Add the web request action

Choose Then: Add an action → Send web request. It sits under the Notifications category, which is easy to scroll past when you are looking for something network-shaped.

Set the request itself:

Field	Value
Web request URL	https://api.katilyst.com/v1/logged-actions
HTTP method	POST
Web request body	Custom data

Then add two headers. These are key and value pairs, added one at a time rather than pasted in together.

Key	Value
Authorization	API-Key followed by your key
Content-Type	application/json

The API-Key prefix is part of the header value, with a space after it. Pasting the token on its own returns a 401, and it is the most common setup mistake on this integration.

Your API key is stored in the rule configuration, where anyone who can edit automation rules in this space can read it. Treat edit access accordingly, and check whether your version of Jira offers a hidden or secret option on header values.

Screenshots in this guide show JIRA Cloud as of October 2026. Atlassian moves things occasionally, so the labels matter more than the exact layout.

5

Build the request body

{
  "userEmail": "{{issue.assignee.emailAddress}}",
  "availableActionId": "1111-2222-3333-action-id",
  "creator": "JIRA Automation",
  "details": "{{issue.key}} — {{issue.summary}}"
}

Only userEmail and availableActionId are required. creator appears in the champion’s action log, so make it recognizable.{{issue.assignee.emailAddress}} reflects the worked example. Swap it for the smart value matching the field you decided to credit — {{issue.reporter.emailAddress}} for the reporter, or {{issue.customfield_XXXXX.emailAddress}} for a user picker field, where the ID comes from your JIRA custom field configuration.

Test the smart value before you rely on it. A custom field that holds free text rather than a JIRA user returns the raw string, and a field left empty returns nothing at all — both produce a 400 from Katilyst.

dateTime is left out on purpose. The field is optional, and Katilyst stamps the action when it receives the call. Because the rule fires the moment the ticket transitions, those two times are the same for practical purposes.Add it if you ever point this rule at historical tickets, where the moment of receipt and the moment of the work would differ by weeks or months.

Leave Delay execution and Validate response at their defaults.

​

Verify

1. Check the rule’s Audit log in JIRA for a successful run.
2. Call List a user’s logged actions and confirm the award landed.

curl "https://api.katilyst.com/v1/projects/{projectId}/users/{userId}/logged-actions" \
  -H "Authorization: API-Key your_key_here"

​

Troubleshooting

• The rule runs and no reward appears. Check status on the logged action. PENDING means the Available Action requires admin approval and is waiting for it, which is program configuration rather than an integration fault. If you see LIMIT_EXCEEDED_TIMEFRAME, that action was submitted inside the platform rather than by your rule — frequency limits do not apply to API calls.
• A 409 response. The champion is not eligible for that Available Action, usually because a condition on it was not satisfied. The request was well formed and the program’s own rules declined it.
• A 400 response. Usually the email does not match a User in that Katilyst Project, or the smart value resolved to something that is not an email address. Check what the audit log shows the rule actually sent, then call List a project’s users to see what Katilyst has on file.
• A 401 response. The key is invalid, missing, or was pasted without the API-Key prefix on the header value. An invalid key is the most common cause — confirm it has not been rotated or revoked since the rule was built.
• Nothing in the audit log. The trigger or conditions did not match. This is the most common outcome on a first attempt, and it almost always means one of the three mappings is off. Strip the rule back to the trigger alone, confirm it fires, then add conditions one at a time.

​

Related