This epic introduces a secure and low-friction way for approvers to cast decisions via direct links, with a particular focus on Atlassian users linked to external approver accounts. The primary goal is to enable approvers to submit decisions (approve / reject / abstain, when available) with minimal UI interaction, while preserving strong security, auditability, and flexible integration options for customers.

The solution consists of:

• an API-key–secured endpoint for retrieving signed action links (24-hour validity)

• a signed voting endpoint

• Atlassian login and account linking for external approvers

• (additional) webhooks that notify customers about approval changes, eliminating the need for periodic polling

1. REST API Key privilege for signed action links (24h)

A new API Key privilege enables customers to programmatically retrieve signed action links for a given approval step.

• New privilege: Get Step Links

• Configurable via the API Key edit form

• Endpoint access requires an API key with this privilege enabled

Endpoint behavior

• Mandatory parameters: approvalId, stepId

• Optional parameter: whether login as an external user is required (true by default)

• Returns signed action links (valid for 24 hours) containing all information in jwt for all available actions

• Clear validation errors for missing or invalid parameters

This allows customers to request links only when needed, without embedding long-lived credentials in URLs.

2. Secure vote endpoint (approve / reject / abstain)

A secure REST endpoint allows external approvers to submit a decision for a specific approval step.

• Mandatory: signed action ink created in point 1, JWT parameter contains information about approval id, step id, action type, and whether login is required

• Supported action values: approve, reject, abstain (if available for the step)

• Security: signed, short-lived token valid for 24 hours

• Optional flag indicating whether login is required (not required by default)

• Available to external approvers, who may have an account in the application

If the user is not logged in and login is required, the endpoint returns an appropriate message and initiates a redirect flow.

UX behavior for linked Atlassian users

• Identity is resolved from the external approver’s user session

• The decision is submitted without a confirmation screen, allowing the browser tab to be closed immediately

Existing users (email-based voting) or users not logged in

• The decision requires confirmation in the UI by confirming the action.

• Users not yet linked to an Atlassian account are informed that linking their account enables confirmation-free voting

3. Atlassian login for external approvers & account linking

Atlassian login is added for external approvers to support seamless, session-based voting.

• On successful login:

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

  • A persistent mapping is created between:

    • the external approver account (our system)

    • the Atlassian user account

This enables smoother UX and reliable identity resolution for direct-link voting.

4. Additional: approval webhooks to avoid polling

As an enhancement, webhook support enables customers to react to real approval changes instead of polling the API.

• Configuration: Webhook URLs configurable in Global Settings

• Events:

  • Approval created

  • Approval step decided (approve / reject / abstain)

  • Approval completed (final approved / final rejected)

• Payload includes: approval, step (if applicable), decision, timestamps

• Security: public key + timestamp endpoint for verification

Outcome:
Customers know exactly when to request step links or refresh approval state, eliminating cyclical polling and improving integration efficiency.