> ## Documentation Index > Fetch the complete documentation index at: https://docs.pipeshub.com/llms.txt > Use this file to discover all available pages before exploring further. # Confluence > Team workspace and documentation platform connector

Confluence

Team workspace and documentation platform

✅ Ready 📖 Documentation Available

## Overview Confluence is Atlassian's team workspace and documentation platform, widely used for knowledge bases, product docs, meeting notes, and collaborative content. The Confluence connector syncs spaces, pages, blog posts, comments, attachments, and user information, enabling comprehensive knowledge-base search across your Confluence content. ### What Gets Synced | Entity | Description | | ------------------ | --------------------------------------------------- | | **Spaces** | Top-level containers (e.g., Engineering, Marketing) | | **Pages** | Full page content with formatting preserved | | **Blog Posts** | All blog post content and metadata | | **Comments** | Comments on pages and blog posts | | **Attachments** | Files attached to pages and blog posts | | **Users & Groups** | User profiles, group memberships | | **Permissions** | Space permissions and content restrictions | *** ## Configuration Guide The Confluence connector supports **two authentication methods**. Both sync the same data — pick whichever fits your rollout. ### Prerequisite: Email Visibility

**Each user in your organization must set their email address to be visible** in order for PipesHub to correctly assign permissions and make records visible to them.

This prerequisite applies to **both** authentication methods (OAuth and API Token). **Why email visibility matters.** PipesHub uses email addresses to match Confluence users with their permissions. If a user's email is hidden: * PipesHub cannot match the user's Confluence account to their PipesHub account * Permissions cannot be synced correctly for that user * The user will not see any Confluence content in PipesHub **How to configure email visibility.** Every user must complete these steps in their Atlassian account: 1. Click your **profile picture** in the top right → select **Account Settings**.

2. Select the **Profile and visibility** tab. 3. Scroll down to the **Contact** section. 4. In the **Who can see this?** dropdown for your email address, select either **Anyone** (recommended) or **Your organization**.

**Do not select "Only you and admins"** — this will prevent PipesHub from accessing your email address and matching you to permissions, making all records invisible to you. 📖 **Official documentation:** [Configure User Email Visibility in Confluence](https://support.atlassian.com/confluence-cloud/docs/configure-user-email-visibility/) This is a **per-user setting** that must be configured by each individual user. Administrators cannot change this setting for other users. We recommend communicating this requirement to your team during the Confluence connector rollout. ### Choose an authentication method | Method | Best for | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **OAuth 2.0 (3LO)** | Multi-user / org-wide rollouts, production — per-user refresh tokens, per-user consent, audit trail. Requires Atlassian Developer Console access. | | **API Token** | Single-account setups, quick POCs, or environments where you cannot register an OAuth app. Fastest path to sync. | #### Step 1: Access the Atlassian Developer Console 1. Go to [developer.atlassian.com/console/myapps/](https://developer.atlassian.com/console/myapps/) and sign in with your Atlassian account (must have admin access to your Confluence workspace). 2. You'll see the **My apps** page where you create and manage OAuth 2.0 integrations.

#### Step 2: Create a new OAuth 2.0 integration 1. Click **Create** in the top-right corner. 2. Select **OAuth 2.0 integration** from the dropdown. 3. Fill in the application details: * **Name:** Enter a meaningful name (e.g., `PipesHub Confluence Connector`). * Check the box to agree to Atlassian's developer terms. 4. Click **Create**.

OAuth 2.0 (3LO) integrations use rotating refresh tokens by default, which improves security by limiting token validity and enabling automatic detection of refresh-token reuse. #### Step 3: Review the application overview After creation, you'll land on the app overview page. It shows: * **App ID** — your application's unique identifier * **Distribution status** — whether the app is shared publicly * **Permissions** — API scopes configured for the app * **Authorization** — OAuth 2.0 (3LO) authorization settings Use the left sidebar to navigate between **Permissions**, **Authorization**, and **Settings**.

#### Step 4: Configure OAuth 2.0 authorization 1. In the left sidebar, click **Authorization**. 2. Find **OAuth 2.0 (3LO)** in the authorization types list. 3. Click **Add** to enable OAuth 2.0 authorization for your app.

4. **Get the Redirect URL from PipesHub:** * In PipesHub, go to **Workspace Settings** → **Connectors**, find **Confluence**, and click **+ Setup** for a new instance. * The connector panel opens as a right-side drawer. On the **Authenticate Instance** tab, copy the **Redirect URL**.

PipesHub Confluence Authenticate Instance tab — copy the Redirect URL

5. Paste the copied URL into the **Callback URL** field in Atlassian Developer Console. 6. Click **Save changes**.

The Callback URL must match exactly between Atlassian Developer Console and PipesHub. Any difference — trailing slash, protocol, casing — causes authentication to fail. #### Step 5: Add API permissions 1. In the left sidebar, click **Permissions**. 2. You'll see a list of available Atlassian APIs. 3. Add scopes for both **User identity API** and **Confluence API**.

**User Identity API scopes** Click **Add** next to User identity API and select: | Scope | Description | | -------------- | ----------------------------------------------------- | | `read:account` | View user profiles (required for user identification) |

The `offline_access` scope is automatically included when you configure OAuth 2.0 (3LO). It enables refresh tokens so scheduled synchronization continues when users are not actively logged in. **Confluence API — Classic scopes** Click **Add** next to Confluence API. You'll see two tabs: **Classic scopes** and **Granular scopes**. Configure scopes from both. First, the **Classic scopes** tab: | Scope | Description | | --------------------------------- | ---------------------------------- | | `read:confluence-content.all` | Read all Confluence content | | `read:confluence-content.summary` | Read Confluence content summaries | | `read:confluence-props` | Read Confluence content properties | | `read:confluence-space.summary` | Read Confluence space summaries | | `read:confluence-user` | Read Confluence user information | | `read:confluence-groups` | Read Confluence group information | | `search:confluence` | Search Confluence content | Classic scopes provide broader access patterns required for certain API endpoints. Some features may not work correctly without them. **Confluence API — Granular scopes** Next, the **Granular scopes** tab. Add these read permissions: | Scope | Description | | --------------------------------- | ----------------------------------------- | | `read:content-details:confluence` | View content details and properties | | `read:page:confluence` | View page content | | `read:blogpost:confluence` | View blog post content | | `read:attachment:confluence` | View and download attachments | | `read:comment:confluence` | View comments on pages and blog posts | | `read:space:confluence` | View space details | | `read:user:confluence` | View user details | | `read:group:confluence` | View groups and memberships | | `read:permission:confluence` | View content restrictions and permissions | | `read:audit-log:confluence` | View audit records | | `read:folder:confluence` | View folder data | | `read:email-address:confluence` | View user email addresses |

Atlassian recommends not adding more than 50 scopes to your app. Both Classic and Granular scopes are required for full connector functionality. #### Step 6: Copy Client ID and Client Secret 1. In the left sidebar, click **Settings**. 2. Scroll to the **Authentication details** section. 3. Copy: * **Client ID** — used as **Client ID** in PipesHub. * **Secret** — used as **Client Secret** in PipesHub. Copy it immediately.

Store the Client ID and Client Secret securely. The secret can be regenerated if needed, but you'll have to update your PipesHub configuration with the new value. #### Step 7: Authenticate Instance tab — enter credentials The connector drawer in PipesHub has three tabs: **Authenticate Instance**, **Authorize**, and **Configure Records**. Start on the **Authenticate Instance** tab. 1. Confirm the **Redirect URL** matches the Callback URL you saved in Atlassian in Step 4. 2. If your admin has pre-registered an OAuth app, pick it from the **OAuth app** dropdown. Otherwise leave it blank and enter credentials manually. 3. Enter: * **Client ID** — from Step 6 * **Client Secret** — from Step 6 * **Atlassian Site URL** — your Confluence site URL (e.g., `https://your-domain.atlassian.net`; no trailing slash) 4. Click **Next** to move to the **Authorize** tab.

Authenticate Instance tab — enter Client ID, Client Secret, and Atlassian Site URL

The **Atlassian Site URL** targets the specific Confluence Cloud site this connector instance will sync. Use the full site URL including `https://` (e.g., `https://acme.atlassian.net`). #### Step 8: Authorize tab — complete the OAuth flow On the **Authorize** tab, all the OAuth authorization work happens. The tab shows an **Authenticate** button to kick off the OAuth handshake.

PipesHub Authorize tab with the Authenticate button

1. Click **Authenticate** to start the OAuth flow. A popup opens to Atlassian's authorization page. 2. Select your Confluence site from the dropdown.

**Authorize using the same email as your PipesHub account.** Using a different email causes permission issues on the PipesHub platform. 3. Review the permissions requested by the connector and click **Accept**.

4. The popup closes and returns you to PipesHub. The connector tile shows an **Authenticated** badge with a **Reauthenticate** option. 5. Click **Next** to move to the **Configure Records** tab. #### Step 9: Configure Records tab — sync settings, filters, and indexing On the **Configure Records** tab, control how the connector syncs and what gets synced. **Sync settings** — configure your synchronization preferences first: 1. **Sync Strategy** — `Scheduled` or `Manual`. 2. **Sync Interval** — how often to sync (default: 60 minutes).

**Scheduled sync** runs automatically at the specified intervals. **Manual sync** requires you to trigger synchronization on-demand. **Sync filters** — determine which content is downloaded from Confluence. Data excluded by sync filters is never downloaded.

Available sync filters: 1. **Space Keys** — filter by Confluence spaces. * Operator: `In` (include only) or `Not In` (exclude) * Value: one or more space keys (e.g., `ENG`, `MKT`, `PROD`). Space keys are case-sensitive. * *Finding space keys:* check your space URL — `https://yourinstance.atlassian.net/wiki/spaces/SPACEKEY/overview` — the `SPACEKEY` is what you need. 2. **Page IDs** — filter specific pages (includes all child pages automatically). * Operator: `In` or `Not In` * Value: one or more page IDs (e.g., `88375321`, `90341377`) * *Finding page IDs:* check your page URL — the number after `/pages/` is the page ID. 3. **Blogpost IDs** — filter specific blog posts. * Operator: `In` or `Not In` * *Finding blogpost IDs:* the number after `/blog/YYYY/MM/DD/` in the URL. 4. **Modified Date** — filter by last modification date. Operators: `Is After`, `Is Before`, `Is Between`. 5. **Created Date** — filter by creation date. Same operators. **Indexing filters** — control what synced data gets processed for AI search. All data is synced, but only enabled content types are indexed. * **Pages:** Index Pages / Index Page Attachments / Index Page Comments (all default: enabled) * **Blog posts:** Index Blogposts / Index Blogpost Attachments / Index Blogpost Comments (all default: enabled) **Example configurations:** * *Sync only Engineering space:* Space Keys → Operator `In`, Value `ENG` * *Exclude archived spaces:* Space Keys → Operator `Not In`, Value `ARCHIVE, OLD` * *Sync specific documentation tree:* Page IDs → Operator `In`, Value `88375321` * *Recent content only:* Modified Date → Operator `Is After`, Date `2024-06-01` * *Index pages but not attachments:* disable the **Index Page Attachments** toggle Click **Save** to save your configuration. PipesHub confirms the instance is ready with a final dialog — **"Instance is configured and ready to sync"** — offering two choices: **I'll do it later** or **Start syncing now**.

Instance is configured and ready to sync — I'll do it later or Start syncing now

Choose **Start syncing now** to kick off the initial sync immediately, or **I'll do it later** to enable the connector without an immediate sync. Monitor the **Indexing Progress** to track sync completion. Use this method when you want the fastest setup and only need a single user account to sync Confluence data. No Atlassian Developer Console access required. #### Step 1: Generate an API token in Atlassian 1. Sign in to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens). 2. Click **Create API token**. 3. Give it a meaningful label (e.g., `PipesHub Confluence Connector`), set an expiry if you want, and click **Create**.

4. Atlassian shows the token **once** — click **Copy** and store it securely.

The API token is shown only once. If you close the dialog without copying it, you'll have to create a new token. The token inherits the permissions of the account that created it. Use an account that can read the Confluence spaces you want to sync — ideally a dedicated integration user rather than a personal account. #### Step 2: Authenticate Instance tab — enter credentials 1. In PipesHub, go to **Workspace Settings** → **Connectors**, find **Confluence**, and click **+ Setup**. 2. The connector panel opens as a right-side drawer with three tabs: **Authenticate Instance**, **Authorize**, and **Configure Records**. 3. On the **Authenticate Instance** tab, pick **API Token** in the **Authentication method** dropdown. 4. Enter: * **Base URL** — your Confluence site URL (e.g., `https://your-domain.atlassian.net`; no trailing slash) * **Email** — your Atlassian account email (the account that created the API token) * **API Token** — the token you copied in Step 1 5. Click **Next**. PipesHub validates the credentials and advances directly to the **Configure Records** tab (the **Authorize** tab is skipped for API Token because the token authenticates on its own).

Authenticate Instance tab with API Token method — Base URL, Email, API Token fields

The **Email** must match the Atlassian account that owns the API token. Using a different email causes authentication to fail. #### Step 3: Configure Records tab — sync settings, filters, and indexing On the **Configure Records** tab, control how the connector syncs and what gets synced. **Sync settings** — configure your synchronization preferences first: 1. **Sync Strategy** — `Scheduled` or `Manual`. 2. **Sync Interval** — how often to sync (default: 60 minutes).

**Sync filters** — determine which content is downloaded from Confluence. Data excluded by sync filters is never downloaded.

Available sync filters: 1. **Space Keys** — filter by Confluence spaces. Operator `In` / `Not In`; value is one or more space keys (case-sensitive). 2. **Page IDs** — filter specific pages. Includes all child pages automatically. 3. **Blogpost IDs** — filter specific blog posts. 4. **Modified Date** — filter by last modification date. Operators: `Is After`, `Is Before`, `Is Between`. 5. **Created Date** — filter by creation date. Same operators. **Indexing filters** — control what synced data gets processed for AI search. * **Pages:** Index Pages / Index Page Attachments / Index Page Comments (all default: enabled) * **Blog posts:** Index Blogposts / Index Blogpost Attachments / Index Blogpost Comments (all default: enabled) Click **Save** to save your configuration. PipesHub confirms the instance is ready with a final dialog — **"Instance is configured and ready to sync"** — offering two choices: **I'll do it later** or **Start syncing now**.

Choose **Start syncing now** to kick off the initial sync immediately, or **I'll do it later** to enable the connector without an immediate sync. ## Supported Features The Confluence connector syncs the following data from your Confluence Cloud workspace: * **Spaces** — all accessible spaces and their configurations * **Pages** — full page content with formatting preserved * **Blog Posts** — all blog post content and metadata * **Comments** — comments on pages and blog posts * **Attachments** — files attached to pages and blog posts * **Users** — user profiles and account information * **Groups** — user groups and memberships * **Permissions** — content restrictions and space permissions * **Folders** — folder structure and organization * **Audit Logs** — activity records for compliance This connector is designed for **Confluence Cloud** only. Confluence Data Center and Confluence Server (on-premise) deployments are not supported. ## Useful Links * **Atlassian Developer Console:** [developer.atlassian.com/console/myapps/](https://developer.atlassian.com/console/myapps/) * **Atlassian API tokens:** [support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) * **OAuth 2.0 (3LO) documentation:** [developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/) * **Confluence API scopes reference:** [developer.atlassian.com/cloud/confluence/scopes/](https://developer.atlassian.com/cloud/confluence/scopes/) *** ## Troubleshooting ### Common issues **Invalid client credentials error (OAuth):** * Verify Client ID and Client Secret are correct — no extra spaces * Check that the OAuth app is active in Atlassian Developer Console * Regenerate the secret if necessary and update PipesHub **Callback URL mismatch error (OAuth):** * Ensure the Redirect URL in PipesHub exactly matches the Callback URL in Atlassian * Check for trailing slashes, protocol differences (`http` vs `https`), or casing * Update both configurations to use the same URL **API token authentication fails:** * Confirm the token was copied correctly — no leading/trailing whitespace * The token may have been revoked or expired; create a new one at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) * Verify the **Email** field matches the Atlassian account that created the token * Verify the **Base URL** matches your Confluence site (must include `https://`, no trailing slash, match `*.atlassian.net`) **Site URL format issues (OAuth: Atlassian Site URL / API Token: Base URL):** * Must include the protocol: `https://` * Must **not** include a trailing slash — use `https://acme.atlassian.net`, not `https://acme.atlassian.net/` * Must match the actual Confluence Cloud site (usually `*.atlassian.net`) * Do not include paths like `/wiki` or `/spaces/...` **Authorization failed (OAuth):** * Verify you're signing in with an account that has Confluence access * Ensure your Confluence site is selected during authorization * Check that all required API scopes are configured **No data syncing:** * Verify the connector status shows **Active** * Check that the authenticating user (OAuth) or token-owning user (API Token) has access to Confluence spaces * Ensure spaces are not restricted or archived * Review sync logs for specific error messages **Token expired or sync stopped:** * OAuth tokens may expire per Atlassian's policies; disable and re-enable the connector to re-authenticate * API tokens can be revoked from the Atlassian account page; generate a new one and update the Authenticate Instance tab * Check if the OAuth app is still active in Developer Console **Permission denied for specific content:** * Verify the authenticating user has read access to the content * Check space permissions in Confluence * Review page restrictions that may limit access If you modify OAuth application settings in Atlassian Developer Console (Client ID, Secret, Callback URL, or scopes), update the configuration in PipesHub and re-authorize. For API tokens, re-enter the token in the Authenticate Instance tab if you regenerate it. ## Data Sync Behavior ### Initial sync * Fetches all accessible content from connected Confluence spaces * Indexes pages, blog posts, attachments, and comments * Respects user permissions for content visibility * Duration depends on the size of your Confluence workspace ### Incremental sync * Uses timestamp-based synchronization to detect changes * Only syncs new or modified content since last sync * Efficiently handles additions, updates, and deletions * Reduces API calls and sync duration ### Permission handling * Syncs content based on the authenticating user's permissions * Each user sees only content they have access to in Confluence * Respects space permissions and page restrictions * Maintains Confluence's access control model *** ## FAQ | | OAuth 2.0 | API Token | | --------------------- | ------------------------------------------ | -------------------------------------- | | **Best for** | Multi-user / org-wide rollouts, production | Single-account setups, quick POCs | | **Credentials model** | Per-user consent, rotating refresh tokens | Single token, long-lived until revoked | | **Prerequisites** | Atlassian Developer Console admin access | Any Atlassian account | Choose **OAuth** for production and anything that needs per-user attribution. Choose **API Token** when you cannot register a developer-console app or just want to get syncing quickly. Both methods sync the same data. | Aspect | Confluence Connector | Confluence Toolset | | --------------- | ----------------------------------------- | ---------------------------------------------- | | **Purpose** | Sync and index Confluence data for search | Enable agents to perform actions in Confluence | | **Data Flow** | One-way (import data into PipesHub) | Two-way (read and write via API) | | **When to Use** | Query/search pages, spaces, blog posts | Create pages, update content, manage spaces | **Example:** Use **Confluence Connector** to search and retrieve documentation. Use **Confluence Toolset** to let agents create or update Confluence pages. There are three common causes: 1. **Email mismatch** - The email used during connector authentication doesn't match your PipesHub account email. This causes permission issues preventing you from accessing synced data. * **Fix:** Reconfigure the connector and authenticate using the same email as your PipesHub account. 2. **Records show in "All Records" but not in search** - Documents display in the All Records section but don't appear in search query results. * **Fix:** Verify sync filters in the connector settings and ensure indexing has completed. Check that the data matches your search query criteria. 3. **Data not yet indexed** - The connector is still syncing or hasn't completed the initial indexing process. * **Fix:** Go to **Settings > Connectors**, check the sync status, and wait for indexing to complete. Yes. When creating a Confluence connector, the admin has the option to apply filters and select specific Confluence spaces for indexing. This allows you to limit the scope of indexed content to only the spaces that are relevant to your organization's needs. Yes. You can achieve this by following these steps: 1. **Create a dedicated connector instance** — Create a Confluence connector instance for the space that contains the pages you want to index. 2. **Select Manual Indexing** — When configuring the connector, choose the **Manual Indexing** option. This gives you granular control over which content gets indexed. 3. **Select the Confluence space** — Use the filters to select the specific Confluence space that contains the pages you want to index. 4. **Navigate to specific pages** — Go to **All Records** in the navigation bar, then browse to the specific pages you want to index within the selected Confluence space. ***

Ready to Get Started?

Connect your Confluence workspace to PipesHub in just a few minutes. Follow the step-by-step guide above to enable organization-wide knowledge search and access across all your Confluence content.