Search pages, blog posts, and their PDF, Word, Excel, and PowerPoint attachments from selected Confluence Cloud spaces. An Agent Serve organization admin enables Confluence; each teammate connects their own account.
| Method | How it works |
|---|---|
| Service account | One account indexes content and permissions. Each teammate connects to match their Atlassian identity to those permissions. |
| Member accounts | Agent Serve indexes the pages each connected teammate can access, using that person's account. |
Before you start
- Use Confluence Cloud. Server and Data Center are not supported.
- Each teammate needs a verified Agent Serve email matching their active Atlassian account's email.
- For a central source, an Atlassian organization admin creates a service account with Confluence access. Grant it access to the chosen spaces and restricted pages, plus permission to read space permissions and the user/group directory. Admin status alone does not bypass page restrictions.
Teammates authorize Agent Serve's shared Confluence app, which also requests workflow permissions, including writes. Search does not edit pages. Hosted Agent Serve provides this app; self-hosted deployments must configure it, even when a service account supplies content.
Set up a central source
Choose Confluence
Open Settings → Sources → Add source and select Confluence. This opens Connect Confluence site with service-account authentication. To connect another site later, open Confluence from the Sources list and select Add Confluence site.
Choose the account and spaces
Under Service account, select a service account or add one. Enter the same Confluence site as the credential, then choose Spaces. All in the dropdown includes every space the syncing account can access at each sync, including spaces it gains access to later. Clear the picker search before selecting all.
If you selected all spaces before this behavior shipped, reselect All and save. Earlier selections stay a fixed list of spaces.
To enter comma-separated keys such as ENG, PRODUCT, use the switch beside Spaces. Switching between the picker and manual entry keeps your selection.
Open More options for content type, labels, and metadata tags. The default is Pages only; choose All content to include blog posts.
Sync and connect your identity
Select Connect & Sync to start indexing. Then open Integrations in the main sidebar and select Connect for Confluence. Authorize the configured site using the Atlassian email matching your verified Agent Serve email.
Each teammate completes this identity connection. An existing authorized account may already cover the site. Confluence appears once in Integrations, even with multiple sites; Connect or Reconnect appears when another authorization is needed.
Connect member accounts
After an admin configures Confluence, open Integrations and select Connect beside Confluence. Authorize your account; you do not enter the site's domain or choose its spaces again.
If Confluence is allowed but no source exists, select Connect beside Confluence. To add another site later, open the Confluence row’s actions menu (…) and select Add Confluence site:
- Open Your account and select a saved account or Connect Confluence account. Authorize using the Atlassian email matching your verified Agent Serve email.
- Enter the hostname under Atlassian site, then choose Spaces. Use All in the dropdown for every space accessible at each sync, or the arrows beside Spaces to enter comma-separated keys. You can select up to 1,000 individual spaces in this form.
- Select Connect & Sync. Agent Serve saves the selected scope and starts indexing with your account.
To configure this method as an admin, open Settings → Sources → Confluence → Add Confluence site and choose Sync using → Member accounts. Enter the site and spaces, then select Add Confluence site. Account for browsing populates the space picker but does not connect that person to Search; manual space keys work without a browsing account. Teammates then connect from Integrations.
Using a service account
Use a scoped API token from an Atlassian service account:
- In Atlassian Administration, open Directory → Service accounts. Create or select the account and grant the Confluence access described above.
- Select Create credentials → API token → Next. Name the token and choose an expiry between 1 and 365 days.
- Add all scopes below. Use the App: Confluence and Scope type filters to find both classic and granular scopes.
read:confluence-content.all
read:page:confluence
read:blogpost:confluence
read:attachment:confluence
read:space:confluence
read:label:confluence
search:confluence
read:confluence-space.summary
read:content.metadata:confluence
read:space.permission:confluence
read:confluence-user
read:user:confluence
read:group:confluenceUse all 13 scopes for account validation, pickers, content, attachments, permissions, and directory reads. Central indexing does not need write scopes.
- Review and create the token, then copy it. Atlassian shows it only once.
- In Agent Serve's source form, open Service account → Add service account. Paste the API token, enter Site domain (hostname only), and select Add service account. Continue in the source form with the same domain.
See Atlassian's account setup and token instructions. Scopes do not grant space or page access. To replace an expiring token or change scopes, add a new credential in the source's Settings, select Change service account, and verify a sync before revoking the old token.
Configuration and indexed content
| Setting | What it controls |
|---|---|
| Confluence site | Cloud hostname only, such as your-team.atlassian.net; omit page URLs and /wiki. |
| Spaces / Space Keys | Required spaces. The picker and manual input set the same scope. |
| Content Type | Pages only (default), Blog posts only, or All content for both. |
| Filter by Label | Optional comma-separated labels; content can match any listed label. |
| Metadata tags | Labels, version, and last-modified tags. |
Search manages the schedule and hides item limits. It indexes published/current content and each page's own text, including supported local callouts and code blocks. PDF, Word .docx, Word 97–2003 .doc, Excel .xlsx, and PowerPoint .pptx attachments on the selected pages and blog posts are indexed as separate documents with their parent's permissions. Space, content-type, and label filters apply to the parent page or blog post.
Archived content, comments, other attachment formats, and expanded Include Page, Excerpt Include, or third-party macro output are excluded. Referenced pages can be indexed separately with their own permissions. Attachments over 100 MB show as skipped. Convert Word 6/95 files to .docx, and .xls and .ppt files to .xlsx and .pptx, before attaching them.
Manage access and sync
Central sources combine space permissions, page and ancestor restrictions, and group membership. Before returning central content, Agent Serve uses your personal connection to check that you still have access to the configured Confluence site. If Atlassian cannot confirm that access, the content is hidden. Member sources use each person's provider listing. Agent Serve admin status does not grant access to all pages, and permission changes take effect after syncing and processing.
Open Settings → Sources → Confluence, then a source's Documents, Settings, or Sync history. Invite teammates through Settings → Members → Invite or SSO, then have them connect through Integrations. People → Request connections only requests a provider connection; it does not invite people to the organization.
Syncing runs automatically. Admins can use Sync now for an immediate update, Pause syncing to stop scheduled syncs, or Resume syncing to restart them. Successful manual syncs have a one-minute cooldown; failed syncs can be retried immediately.
In Sync history, Continuing means a healthy listing needs another batch. Partial means the sync did not fully succeed; read the accompanying notice. If permissions could not be verified, the last successful sync time stays unchanged and documents without verified access remain hidden from Search.
Troubleshooting
| Problem | What to check |
|---|---|
| Connect & Sync is disabled | Select a service account, enter its site domain, and choose at least one space. |
| Space picker is empty or fails | Check the domain, account's space access, and read:space:confluence scope. Manual space keys are also supported. |
| Service-account validation fails | Check token expiry, site, Confluence app access, and the full scope list above, including read:confluence-user. |
| Content syncs but Search is empty | Connect your personal Confluence identity. Check permission/directory sync errors and group-read scopes. |
| Permission verification incomplete | Open the source's Sync history. Check the service account's space, page, and directory access. If access is correct and the warning persists, ask your operator to inspect the connector run's permission errors, including incomplete or repeated permission pages. Documents without verified access stay hidden; do not broaden sharing to clear the warning. |
| A new page, blog post, or label is missing | Confluence search can take time to update. Once the content appears in Confluence search with the selected label, sync again. |
| Attachments are missing | Check read:attachment:confluence and access to the parent page. A service-account token created before attachments were indexed may need to be replaced with one that includes this scope. Pages keep syncing, and attachments that could not be listed are kept rather than removed. |
| A restricted page is missing | Both your account and the crawling account need access to the page and its ancestors. |
| Embedded content is missing | Index the referenced page separately; remote macro output is excluded. |
| Reconnect or email mismatch | Authorize with the Atlassian account matching your verified Agent Serve email and grant all requested permissions. |
Open a missing page as the affected teammate, check its space and page restrictions, then sync again after correcting access. See Atlassian's content access and permission inspection guides.
Self-hosted operator setup
Configure one shared Confluence OAuth app for teammates' connections:
- In the Atlassian developer console, select or create the deployment's OAuth 2.0 integration.
- Under Authorization → OAuth 2.0 (3LO), add
https://<your-agentserve-domain>/api/auth/oauth2/callback/confluenceas a callback. - Under Permissions, add the Confluence API and its full
confluencescope list from Agent Serve's OAuth configuration, includingread:group:confluence. Add User Identity API → read:me. Agent Serve requestsoffline_accessfor refresh tokens; the service-account list above does not replace this shared OAuth scope set. - Enable sharing under Distribution. Set
CONFLUENCE_CLIENT_IDandCONFLUENCE_CLIENT_SECRETfrom the app's Settings, verifyNEXT_PUBLIC_APP_URL, and restart Agent Serve. - Connect from Integrations and select the configured site. After changing the OAuth client or requested scopes, use Settings → Sources → More → Update sign-in settings, then have affected teammates reconnect.
The callback must match Agent Serve's scheme, hostname, port, and path exactly. If only the app owner can connect, check Distribution. See the Atlassian OAuth guide and Agent Serve deployment reference.