Skip to main content

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 Logo

​
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

EntityDescription
SpacesTop-level containers (e.g., Engineering, Marketing)
PagesFull page content with formatting preserved
Blog PostsAll blog post content and metadata
CommentsComments on pages and blog posts
AttachmentsFiles attached to pages and blog posts
Users & GroupsUser profiles, group memberships
PermissionsSpace 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.
Access User Profile Settings
  1. Select the Profile and visibility tab.
  2. Scroll down to the Contact section.
  3. In the Who can see this? dropdown for your email address, select either Anyone (recommended) or Your organization.
Set Email Visibility to 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
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

MethodBest 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 TokenSingle-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/ 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.
Atlassian Developer Console - My Apps

​
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.
Create OAuth 2.0 Integration Form
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.
Application Overview Page

​
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.
Add OAuth 2.0 Authorization
  1. 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
  1. Paste the copied URL into the Callback URL field in Atlassian Developer Console.
  2. Click Save changes.
Add Callback URL in Atlassian
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.
Add API Scopes
User Identity API scopesClick Add next to User identity API and select:
ScopeDescription
read:accountView user profiles (required for user identification)
User Identity API Scopes
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 scopesClick Add next to Confluence API. You’ll see two tabs: Classic scopes and Granular scopes. Configure scopes from both.First, the Classic scopes tab:
ScopeDescription
read:confluence-content.allRead all Confluence content
read:confluence-content.summaryRead Confluence content summaries
read:confluence-propsRead Confluence content properties
read:confluence-space.summaryRead Confluence space summaries
read:confluence-userRead Confluence user information
read:confluence-groupsRead Confluence group information
search:confluenceSearch Confluence content
Classic scopes provide broader access patterns required for certain API endpoints. Some features may not work correctly without them.
Confluence API — Granular scopesNext, the Granular scopes tab. Add these read permissions:
ScopeDescription
read:content-details:confluenceView content details and properties
read:page:confluenceView page content
read:blogpost:confluenceView blog post content
read:attachment:confluenceView and download attachments
read:comment:confluenceView comments on pages and blog posts
read:space:confluenceView space details
read:user:confluenceView user details
read:group:confluenceView groups and memberships
read:permission:confluenceView content restrictions and permissions
read:audit-log:confluenceView audit records
read:folder:confluenceView folder data
read:email-address:confluenceView user email addresses
Confluence API Granular Scopes - Part 1
Confluence API Granular Scopes - Part 2
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.
OAuth 2.0 Credentials
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.
Choose Confluence Site
Authorize using the same email as your PipesHub account. Using a different email causes permission issues on the PipesHub platform.
  1. Review the permissions requested by the connector and click Accept.
Accept OAuth Permissions
  1. The popup closes and returns you to PipesHub. The connector tile shows an Authenticated badge with a Reauthenticate option.
  2. 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).
Configure Sync Strategy
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.
Confluence Filters Configuration
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.

​
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.

​
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
  • 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.0API Token
Best forMulti-user / org-wide rollouts, productionSingle-account setups, quick POCs
Credentials modelPer-user consent, rotating refresh tokensSingle token, long-lived until revoked
PrerequisitesAtlassian Developer Console admin accessAny 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.
AspectConfluence ConnectorConfluence Toolset
PurposeSync and index Confluence data for searchEnable agents to perform actions in Confluence
Data FlowOne-way (import data into PipesHub)Two-way (read and write via API)
When to UseQuery/search pages, spaces, blog postsCreate 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.