Skip to content
Leverage AI Developer Support

Confluence Connector

Use this page when you need the Atlassian-side setup direction for Confluence. For shared connector behavior, start with Connectors Overview and Provider Auth And Setup.

Runtime Shape

Section titled “Runtime Shape”
  • Runtime status: implemented, live-only, read-only
  • Connector key: confluence
  • Live domain and canonical tool: knowledge-page through knowledge-page-live-query
  • Auth bindings:
    • Better Auth generic OAuth provider id atlassian for Confluence Cloud user-account access
    • Confluence Data Center user-managed PAT through the web app user-api-key strategy
    • Confluence Data Center company-managed service/bot PAT through the customer CMS deployment-api-key profile
  • Required resource selection:
    • Save Confluence spaces as { mode: "all" } or { mode: "selected", ids: [...] }.
    • The runtime does not silently default to all spaces when no saved selection exists.
  • Supported live coverage:
    • spaces, pages, labels, comments, ancestors, children, page metadata, and attachment metadata
    • page title/text search, pages in a space, page detail/snippet reads, recently updated pages, pages by label, comments, page tree relationships, and attachment metadata
  • Current limits:
    • no indexed sync, Meltano tap, embeddings, sync button, write action, Cloud API-token Basic auth, attachment file-content extraction, or retained page content
    • no first-class Confluence blog post, whiteboard, database, or folder objects in this pass

Cloud OAuth Setup

Section titled “Cloud OAuth Setup”
  • Confluence Cloud uses the shared Atlassian OAuth provider id atlassian.
  • OAuth connects through the Atlassian gateway with an explicit siteId/cloudId.
  • Runtime calls Confluence Cloud through https://api.atlassian.com/ex/confluence/{cloudId}.
  • Required scopes are defined in packages/domain/src/connectors/connectorRegistry.ts and include offline access, identity, search, space/page read, label/comment/user/content metadata, hierarchy, and attachment read scopes.
  • The Cloud runtime uses embedded page/comment profile labels when provider payloads include them and uses the Confluence v2 bulk-user lookup to resolve returned account ids when needed. Atlassian privacy settings may still hide profile labels; in that case answers omit the person label or say it is unavailable rather than exposing raw account ids or emails.
  • Cloud API-token Basic auth is not supported for this connector. Cloud email-plus-token Basic auth is a different auth scheme from Data Center bearer PATs.

Data Center User PAT Setup

Section titled “Data Center User PAT Setup”
  • The web user enters their own Confluence Data Center PAT in the web app.
  • API validates the PAT through the configured Data Center base URL and /rest/api/user/current.
  • The raw PAT is encrypted in API-owned user credential storage and scoped to that signed-in web user plus connector row.
  • Data Center base URLs should include any context path such as /wiki.
  • Data Center URL validation rejects Atlassian Cloud gateway/site URLs such as api.atlassian.com and *.atlassian.net.

Company-Managed Data Center PAT Setup

Section titled “Company-Managed Data Center PAT Setup”
  • Data Center PAT setup:
    • Create a dedicated Confluence service/bot user.
    • Grant that user only the spaces/pages the deployment connector should expose.
    • Create a Data Center personal access token for that service/bot user.
    • Enter the Confluence base URL and PAT in customer CMS. The PAT is stored only through the secret slot backend; the CMS record stores safe readiness/config metadata.
    • Do not enter a Confluence Cloud site URL or https://api.atlassian.com/ex/confluence/<cloudId> in this profile. Cloud API tokens use email-plus-token Basic auth and require a separate future profile decision.
    • If validation fails, CMS does not save the attempted Confluence URL or PAT. Correct the URL/PAT and validate again.
    • If the company-managed PAT must be removed, use the CMS remove action. It clears the saved PAT slots and Confluence setup fields; company-managed Confluence connector rows are unavailable until an operator validates a new PAT.
    • Company-managed answers come from the shared service/bot user’s Confluence permissions, not the signed-in web user’s Confluence identity.

Provider-Specific Gotchas

Section titled “Provider-Specific Gotchas”
  • Atlassian calls Data Center tokens personal access tokens, but deployment-scoped setup must use a dedicated service/bot user PAT. Do not ask customers to paste an employee’s personal PAT for a company-managed connector.
  • Company-managed Confluence access is limited by the service/bot user’s Confluence permissions and the connector-selected spaces. It is not proof of the web user’s own Confluence account permissions.
  • Company-managed Confluence access must fail closed whenever the CMS profile is not ready, including after an operator removes the saved PAT profile.
  • Web copy must clearly say whether Confluence sees the user’s own account, the user’s Data Center PAT account, or the company-managed service/bot account.
  • Confluence Cloud API-token Basic auth is not this Data Center PAT profile. If product accepts Cloud API-token support later, document it as a separate credential profile because the auth scheme and ownership model differ.
  • Confluence Data Center PAT validation rejects Atlassian Cloud gateway/site URLs before storing or sending the PAT, so a Cloud URL in CMS indicates the wrong auth strategy rather than a copied-token problem.
  • Confluence search uses provider lexical/CQL search and bounded reads. It is not semantic whole-wiki recall.
  • Source metadata and grounding use space/page titles, account labels, timestamps, safe URLs, and provenance. Raw Confluence page, space, comment, and account ids are not shown as generic source metadata unless a future identifier-specific flow requires them.
  • Attachment support returns metadata only; file contents are not fetched or extracted.

Canonical Sources

Section titled “Canonical Sources”
  • packages/domain/src/connectors/connectorRegistry.ts
  • apps/cms-customer/src/connectors/defaultConnectorCatalog.ts
  • apps/cms-customer/src/collections/ConnectorCredentialProfiles.ts
  • docs/features/connectors/spec.md
  • docs/features/live-query/spec.md

Official Docs

Section titled “Official Docs”