Why

Customers who run part of a process outside Jira have to walk a human through a browser to record a decision. The Web API can create, delete and archive approvals and mint a signed action link, but every such link requires a login, which ends the road for an unattended process.

One operation is missing: record a decision with a comment on a given approval, on behalf of a given approver. The planned conversational agent needs the same operation, so the rules and the audit trail are built once and serve both.

What the user can do

1. A global administrator enables the option in global settings. Off by default.

2. The definition offers "Allow decisions through the Web API". While the global setting is off the control is disabled and states that it has to be enabled in global settings first. A value saved earlier stays, so re-enabling the global setting restores the administrator's intent.

3. The administrator grants an API key the right to submit decisions. The key acts as its owner by default. The administrator can switch it to the mode where the API client names the person, and the key then decides on behalf of someone from a chosen group.

4. The external system calls one operation: approval, optional step, decision (approve, reject, abstain, consent), comment, person, request id. No browser, no login, no action link.

5. The same rules apply as in the interface: approver eligibility on an active step, delegations, required comment, decisions allowed for the step, whether the step is still active, and whether the approval is archived, past its deadline or outdated. The engine enforces them, not the caller.

6. The history and the step show that the decision came from the Web API, who made it and what submitted it: key name and fingerprint, key owner, source IP. A global administrator gets a link to the key usage details from there.

Decisions taken outside the panel (e-mail link, Slack, external approver portal) are marked with their channel in the history as well. Panel decisions stay unmarked.

Acceptance criteria

1. Global settings hold a "decisions through the Web API" toggle, off by default, visible to a global administrator only.

2. While the global toggle is off, the definition option is disabled and explains that it must be enabled in global settings. The value saved on the definition is not cleared.

3. Submitting decisions is a separate privilege on an API key, not granted by default, and not selectable while the global toggle is off.

4. A call is refused with an actionable message when: the global toggle is off, the definition does not allow it, the key lacks the privilege, the named person is not an approver on an active step, a required comment is missing, the decision is not allowed for the step, the step is no longer active, or the approval is archived, past its deadline or outdated.

5. In the mode where the API client names the person, that person must belong to the group configured on the key and must have real access to the work item or page. Otherwise the call is refused and the attempt is recorded in the instance error feed.

6. The step is resolved automatically when the person has exactly one actionable step. With more candidates nothing is written and the candidates are returned. Never a first match.

7. A repeated call carrying the same request id does not create a second decision.

8. The decision is visible in the approval history and on the step as submitted through the Web API, with the key name and fingerprint, the key owner and the source IP.

9. A global administrator gets a link from there to the key usage details, including for a key that has since been archived. Other users see the description without a link.

10. The history marks the channel only for decisions taken outside the panel. Panel decisions and entries predating this change carry no marking, while the CSV export of the history and the decision webhook always carry the channel, panel included.

11. Turning the global toggle off takes effect immediately, including approvals started while it was on.

12. Vote steps are not supported and are refused with a clear message.

13. The Web API documentation covers the new operation, both toggles and the new privilege.

Constraints

• API keys are created by global administrators only. The default mode, where the key acts as its owner, would therefore record decisions as the administrator and is of no use in a real deployment. The mode that will actually be used is the one where the API client names the person, and that is where the whole risk sits. It must not be presented as the safeguard.

• A key is a secret of the customer's system. "X approved" is that system's attestation, not proof that X clicked. Hence the double opt-in, global and per definition, and the visible channel in the history. The administrator turning this on takes that risk and has to see it stated in the interface.

• A key holding this privilege with an unrestricted IP range is flagged on the key list and warned about when the key is saved.

• Vote steps are out of scope for this version.