Connect Confluence to Athena: Pages and Search

Connect Confluence Cloud to Athena so each member can search with CQL, read pages and comments, browse spaces and page trees, and create, update, or comment on pages as their own Atlassian identity. Confluence space permissions and page restrictions apply unchanged; Athena sees exactly what you can see in Confluence, every page or comment it writes is attributed to you, and nothing is shared through a service account or personal access token.

​

Step 1: Register an OAuth app in Atlassian (Atlassian admin)

One app registration serves every user and every Confluence site in your organization; Atlassian works out which site a request targets at runtime.

1. Open developer.atlassian.com → your profile icon → Developer console → Create → OAuth 2.0 integration. Name it e.g. Athena.
2. When asked about the grant type, choose account-level grants (not resource-restricted). Athena’s multi-site flow depends on it: a member’s single consent can then cover several Confluence sites, and connecting again adds another site to the same grant. With a resource-restricted app each consent covers only the site the member picks, so in Athena connecting again replaces that site instead of adding one. This choice is made at creation and cannot be changed later.
3. Permissions: add both the Confluence API and the User Identity API. On the Confluence API open the Granular scopes tab (the Confluence REST API v2 that Athena uses only accepts granular scopes) and enable:
   read:space:confluence
   read:page:confluence
   write:page:confluence
   read:comment:confluence
   write:comment:confluence
   read:hierarchical-content:confluence
   read:content-details:confluence
   read:user:confluence
   
   On the User Identity API enable read:me. Athena also requests offline_access automatically; it is not a scope you enable in the console. read:me lets Athena identify who connected; offline_access keeps the connection alive without re-prompting members. Atlassian forces every member to re-consent if the scope set changes later, which is why the write scopes are included up front; every write still asks the member for approval inside Athena.
4. Authorization → Configure: set the callback URL:
   https://api.athenaintel.com/api/direct-connectors/confluence_direct/oauth/callback
   
   For private/VPC deployments, replace api.athenaintel.com with your environment’s Athena API host. Atlassian requires an exact match; if the console only accepts one callback URL, register a separate app per Athena environment.
5. Distribution → Enable sharing and complete the form (vendor details and a privacy-policy URL). Without sharing, only the app’s creator can connect; everyone else gets an Atlassian error. Until the app passes Atlassian’s optional review, members see a “not yet reviewed by Atlassian” note on the consent screen; that’s expected for private integrations.
6. From Settings, copy the Client ID and Secret and send them to your Athena Intelligence contact through a secure channel.

​

Step 2: Enable Confluence in Athena (Athena Intelligence, once)

Athena Intelligence registers a Confluence integration for your workspace from the Client ID and Secret you sent in step 1.6 (provider confluence_direct, OAuth 2.0, the scopes from step 1.3) and confirms when it is enabled; from then on the Connect Confluence button works for every member. Secrets are encrypted at rest and never returned to the browser. If you share one Atlassian app with Jira, Confluence still gets its own integration with the same Client ID and Secret.

​

Step 3: Connect your account (each member)

1. Navigate to Integrations, find Confluence under Documents & Knowledge, and click Connect on the Confluence card, then Connect Confluence in its details.
2. A popup opens Atlassian’s consent screen. It names the site it will install on (“Install app on your-site.atlassian.net”) and lists the Confluence permissions being granted; approve it. Athena stores your encrypted tokens on its servers and syncs every Confluence site in your Atlassian grant, not just the one named on this screen, so there is no picker step on the Athena side.
3. Have more than one Confluence site? Click Connect Confluence again and select the next site; Atlassian adds it to your existing grant.

Once connected, the Confluence toolkit lets agents search with CQL, read pages (as source or as the rendered page) and their footer or inline comments, list spaces, and list the pages in a space or under a parent page. These read tools run without an approval prompt; your Confluence permissions still bound every result. The toolkit can also create a page (published or draft), update a published page (replace or append, publishing a new version), and add a footer comment or reply; each of these asks for your approval first and is attributed to you in Confluence.

​

Troubleshooting

Quoted text is Athena’s exact wording. Connect errors arrive as a notification beginning “Failed to connect Confluence:”; errors during a chat are relayed by the agent in its own words, so search this list for a distinctive phrase rather than the whole sentence.

• “No enabled oauth2 Integration is registered for Confluence (Direct)…” You clicked Connect before Athena Intelligence registered the app for your workspace (Step 2). Ask your Athena contact to confirm it is enabled, then connect again.
• “No Confluence connection found. Connect Confluence (Direct) from the Integrations page first…” You have not connected Confluence in this workspace yet; follow Step 3.
• “Confluence authentication failed. Reconnect Confluence (Direct) from the Integrations page…” Read the part after “Confluence’s response:” first. “invalid_grant” or “Unknown or invalid refresh token” means the connection expired or was revoked; Atlassian does that after 90 days of inactivity, on password changes, on SSO migrations, and when you remove the app at id.atlassian.com → Connected apps , and reconnecting fixes it. A missing Confluence license, a missing scope, or an app not installed on the site is Confluence refusing your account; reconnecting will not help; ask your Atlassian admin.
• Missing results from some spaces or pages? No error appears: Confluence filters content you cannot see, so space listings show only the spaces you can view and searches skip restricted pages. Asking for a space key you cannot see fails with “No Confluence space with key … is visible to you on …”.
• “Confluence returned 404, the page, space, or comment does not exist or is not visible to your Confluence user.” A page, comment, or parent asked for by id or URL is missing or restricted; Confluence reports a page you cannot open the same way as one that does not exist.
• “Confluence rejected the update because the page changed since it was read (version conflict).” Someone edited the page between Athena reading it and writing the update. Ask Athena to read the page again and retry; the earlier version stays in the page history.
• “Page … is draft, not a published page…” (or archived or trashed in place of draft). Athena only updates published pages, so that an edit can never publish a draft or resurrect an archived page by accident. Publish or restore the page in Confluence, then retry.
• “Atlassian is rate-limiting requests for this account. Wait a moment and try again.” Atlassian gives each OAuth app an hourly request budget shared by everyone who connects through it. Before showing this message Athena retries twice, waiting as long as Atlassian’s Retry-After header asks (up to 15 seconds each time). A write is retried only when Atlassian confirms it was not processed, so throttling cannot create a duplicate page or comment.
• Connect refused: “Atlassian authorized … but …” The connect is refused rather than saved when the grant reaches no Confluence site, because such a connection cannot answer a single question. The message names the cause:
  • “…but the grant carries no Confluence scopes”: the OAuth app has no Confluence permission. In developer.atlassian.com open the app → Permissions → Confluence API → Configure, and make sure the scopes from step 1.3 are checked on the Granular scopes tab.
  • “…returned N authorized resource(s), but none of them expose Confluence”: Atlassian listed sites for the grant but none was usable. This is rare; connect again, and if it repeats contact Athena support. (Installing the app on a site without Confluence does not produce this message: that connect succeeds and the first Confluence question fails with the authentication message above, whose tail names the problem.)
  • “…but its accessible-resources index reports no sites”: Atlassian’s list of sites for the grant came back empty even though consent succeeded. First, a one-minute check: open id.atlassian.com → Connected apps as the connecting user. That page lists the sites the app is installed on for you; if it shows none, the app is not installed on a site, which is separate from scopes and licensing. If the site is listed there, ask Athena Intelligence to pin your Confluence host (e.g. your-site.atlassian.net) on the workspace’s Confluence integration, and connect again. Athena then reaches the site directly and verifies the connection against Confluence before accepting it. If Confluence refuses, the connect fails with “Atlassian’s site index is empty, and Confluence refused the pinned site(s) …” followed by Confluence’s own error; “…could not be reached to verify the grant” is temporary; try again in a minute. If you already pinned a site and still see the “reports no sites” message, the pinned host did not resolve: it must be an existing bare your-site.atlassian.net host.
• Removed a site from your grant in Atlassian? Athena refreshes your site list each time you click Connect Confluence; the removed site is retired then, and consenting for it again restores it. When Atlassian’s site index is empty and your workspace relies on a pinned site, Athena cannot prove a site is gone and keeps it; use Remove Connection and connect again to drop it.

​

Disconnecting

• In Athena, open the menu on your Confluence connection catalog, choose Remove Connection, and confirm with Remove. Removing the connection also retires every Confluence site under it, so agents can no longer reach Confluence as you.
• To revoke at the source, remove the app under id.atlassian.com → Connected apps; Athena’s next call fails with the authentication message above.
• Workspace admins have no self-serve control in Athena over another member’s connection. Ask the member to remove it or revoke it at id.atlassian.com, or contact Athena support, which can revoke a member’s connection for you.

​

Known limits

• Reads cover pages (by id or URL), spaces, page trees, and page comments. Blog posts appear in search results but cannot be opened; attachments are not read.
• Writes cover pages and footer comments. Attachments, labels, inline comments, and blog posts cannot be created or edited.
• Confluence Cloud only: Confluence Data Center and Server are not supported.
• Connect a given Atlassian account from only one Olympus workspace. Connecting the same account from a second workspace is unsupported and can leave the connections needing to reconnect.