Skip to content
Flowdence Flowdence Docs

API Authentication

Purpose

Section titled “Purpose”

ApprovalFlow exposes Forge app REST APIs for external callers. This page covers the 3-legged OAuth (3LO) setup, required scopes, and base URL formats you need before using the endpoint reference.

Info: Atlassian currently documents Forge app REST APIs as a Preview capability for Confluence and Jira. ApprovalFlow uses that Forge apiRoute model for its external API surface.

Before You Start

Section titled “Before You Start”

Make sure:

  1. ApprovalFlow is installed on the Confluence site you want to call.
  2. A site or organization admin can manage Connected apps in Atlassian Administration.
  3. You can create a 3LO integration in the Atlassian Developer Console.

Step 1: Enable App REST APIs

Section titled “Step 1: Enable App REST APIs”

Forge app REST APIs are disabled per site by default. A site or organization admin must enable them first:

  1. Open Atlassian Administration.
  2. Go to Apps -> Sites and select the Confluence site where ApprovalFlow is installed.
  3. Open Connected apps.
  4. Find ApprovalFlow and open the app details.
  5. Enable App REST APIs.

If this toggle is off, external API calls to ApprovalFlow will fail even if your token and scopes are correct.

Step 2: Create a 3LO Integration

Section titled “Step 2: Create a 3LO Integration”

Create an OAuth 2.0 integration in the Atlassian Developer Console, then connect it to the ApprovalFlow app installed on your Confluence site.

When you add ApprovalFlow in the integration permissions screen, select:

Atlassian Product Scope

Section titled “Atlassian Product Scope”
ScopePurpose
read:forge-app:confluenceRequired by Atlassian for external access to Confluence Forge app REST APIs.

ApprovalFlow Custom Scopes

Section titled “ApprovalFlow Custom Scopes”
ScopeUsed By
read:change-set:customList change sets, get change set detail, preflight change sets
write:change-set:customCreate, update, archive, and submit change sets
read:approval:customPreflight a single page
write:approval:customSubmit a single page for approval

Select only the scopes your integration needs. ApprovalFlow’s custom scopes are defined in the app’s custom-scopes.yaml, and the endpoint-to-scope mapping is documented in the REST API reference.

Step 3: Obtain an Access Token

Section titled “Step 3: Obtain an Access Token”

After configuring the integration:

  1. Set a callback URL in the integration’s Authorization settings.
  2. Use the generated authorization URL to complete the 3LO consent flow.
  3. Exchange the returned authorization code for an access token.

Send the resulting bearer token with every API request:

Authorization: Bearer <access_token>

The authenticated Atlassian user is resolved automatically from the token. ApprovalFlow does not accept a user ID in the request body for API-authenticated actions.

Base URL Patterns

Section titled “Base URL Patterns”

Atlassian documents two supported base URL patterns for Forge app REST APIs:

https://api.atlassian.com/svc/confluence/<cloud-id>/apps/<app-id>_<env-id>
https://<your-site>.atlassian.net/gateway/api/svc/confluence/apps/<app-id>_<env-id>

Where:

  • <cloud-id> is your site’s cloud ID.
  • <app-id> is the ApprovalFlow Forge app ID.
  • <env-id> is the Forge environment ID.

The site-relative base URL is also surfaced in Connected apps after App REST APIs are enabled.

All endpoint paths in the REST API reference are relative to one of these base URLs.

Audit and Identity Behavior

Section titled “Audit and Identity Behavior”

ApprovalFlow records API-initiated actions differently from manual UI actions:

  • The real Atlassian user is resolved from the 3LO request context.
  • ApprovalFlow records the OAuth client ID for traceability.
  • Audit records for API-created or API-submitted actions are tagged as API-driven.

This lets you distinguish automated submissions from manual submissions in the audit trail.

Section titled “Related”