Overview

This feature enables external approvers to perform actions (approve, reject, abstain, consent) on approval steps via secure signed links. These links can be generated by API consumers through the REST API.

---

REST API Key Privilege for Signed Action Links

A new REST API Key privilege (Get Step Action Links) allows API consumers to generate signed action links for approval steps.

• New Get Step Action Links permission added to the API Key form

• Access to the new endpoints is restricted to API keys that explicitly have this permission enabled

• REST API endpoint: GET /webapi/v2/approvals/{approvalId}/steps/{stepId}/links - returns signed action links for a specific step

• REST API endpoint: GET /webapi/v2/approvals/{approvalId}/links - returns signed action links for all active steps of an approval

• Links are signed with short-lived JWT tokens (configurable 1-24 hours, default 24)

• Each link includes the action to perform (e.g. approve, reject, abstain, consent) - more secure, action cannot be tampered with

• Token contains: approval ID, step ID, host ID, expiration, and whether login is required

• API-generated links always have loginRequired=true — ensures the user must be logged in and linked to an Atlassian account

---

Step Action Handler

Build the page that external approvers visit when they click signed action links. This is the consumption side of the links generated above. The endpoint is protected with a signed short-lived JWT token. The action is embedded in the token.

Also includes unification of email direct action links with the new step-action endpoint.

How it works

1. User clicks a signed link (e.g. https://app.approval-path.com/step-action?token=JWT)

2. The system validates the JWT token (signature, expiration, required fields)

3. The system loads the approval and verifies the step is still active

4. Based on the link source and user identity, one of the following happens:

For API-generated links (always loginRequired=true):

API-generated links require the user to be logged in as an external approver and linked to an Atlassian account. The system verifies that the linked Atlassian user is eligible to act on the step (considering delegation). This ensures only authorized users can execute actions.

• If user is not logged in → redirect to login page

• If user is logged in but not linked to an Atlassian user eligible for this step → show access denied message

• If user is linked and eligible, and no comment is required → action is executed directly on the backend (fast path). The user does not need to see a confirmation page; the browser tab can be closed immediately. This is safe from antivirus/link scanners because they don't have an external approver session.

• If user is linked and eligible, and comment is required → a comment form is shown. The user enters a comment and submits.

There is no option for an API-generated link to work for an external approver not linked to an Atlassian user who is eligible to act on that step.

For email action links (user identified by token):

• The token contains the user's identity and the action from the email notification

• The action is executed after confirming decision via JavaScript. This is safe from email antivirus/link scanners because scanners don't execute JavaScript.

• If a comment is required, a comment form is shown instead of auto-executing.

• After successful execution, an info panel is shown suggesting the user can link their Atlassian account to perform actions instantly without confirming action.

• If user has linked Atlassian account in external dashboard, then action is made without the need of manually confirming it.

For comment-required steps:

• When a step requires a comment (based on global settings and step configuration), a comment form is shown instead of auto-executing

• The user must enter a comment before submitting the action

• Comments are stored directly in the approval system (max 1000 characters)

• Similarly for vote step options if using web api action links, there is confirmation with options to choose from. Email action links, for voting, will redirect to Jira/Confluence.

Unification with existing email direct action links

Currently, email "actions without login" links use a separate URL (/submit-action.html) and a separate token format. As part of this work, we unify both email and API action links under the same endpoint (/step-action) and token format. This simplifies the architecture:

• One handler for all external approval actions

• One token format with the action embedded and optional user identity (present for email links, absent for API links)

• Old email links already sent continue to work (backward compatible)

• New email notifications will use the unified format

---

Atlassian Login for External Approvers

Enable external approvers to log in using their Atlassian account. This is required for API-generated step action links — linked Atlassian users can be verified as eligible to act on steps. Additionally includes the database foundation for Atlassian account linking (atlassianAccountId, firstName, lastName fields).

Login via Atlassian is already implemented in External Share for Confluence (CES), so this solution reuses the same approach.

Atlassian Login

Add "Login via Atlassian" as a login option for external approvers.

Flow:

• User clicks "Login via Atlassian" on the login page

• Redirected to Atlassian's OAuth authorization page

• On successful authorization, redirected back to our app

• If the user already has an account (by email match): log in and link the Atlassian account

• If the user is new: show an activation form to complete registration

On successful login:

• Atlassian user details (accountId, email, name) are persisted in the approval_user table

• A persistent mapping is created between the external approver account and the Atlassian user account

• This allows linking our internal user with the Atlassian user account

---

User Settings Page

Implement a Settings page following the same structure and UX as in CES, with three tabs:

a) Profile

• Display email (read-only)

• Edit first name and last name

• Allow linking with an Atlassian account if it has not been linked yet

b) Password

• Allow the user to change their password

c) Delete Account

• Allow the user to permanently delete their account

---

Acceptance Criteria

Token & API Links

• Endpoint returns links for each possible action for the selected step

Step Action Handler

• Signed action links are functional — clicking them opens the step action page

• API links require the user to be linked to an eligible Atlassian account — otherwise access denied

• There is no option for an API link to work for an unlinked external approver

• Linked and eligible users get the fast path: action executed on backend, no confirmation needed, tab can be closed

• Supports all actions: approve, reject, abstain (if enabled), consent

• Prevents action submission on behalf of unauthorized users

• The step is updated to reflect the decision

• Actions on non-active steps show a clear error message

• Invalid or expired tokens show a clear error message

• Comment-required steps show a comment form (comment is mandatory before submitting)

• Email action links auto-execute via JavaScript (safe from antivirus/link scanners)

• Email direct action links are migrated to the new unified handler

• Old email tokens still work via the existing handler (backward compatibility)

• After email action execution, an info panel suggests linking Atlassian account for faster future actions

User Settings

• Existing users can link their Atlassian account from Settings

• Settings page has three tabs: Profile, Password, Delete Account

• Profile tab shows email, allows editing first/last name, shows Atlassian link status

• Password change works with current password validation

• Account deletion works with session cleanup

Old email action links should also be tested since we unified mechanism for both webapi action links and email action links.