Confluence (Direct OAuth)

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 connect flow relies on it: a member’s single consent can then cover several Confluence sites, and connecting again adds another site to the same grant. A resource-restricted app limits each consent to one site and connecting again replaces the site instead of adding it. 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 hand them to your Athena workspace admin through a secure channel.

​

Step 2 — Enable Confluence in Athena (workspace admin, once)

Open Workspace Settings → Treasury → Integrations and add a new integration: Leaving scopes empty in the config uses Athena’s defaults (the set from step 1.3). Enable the integration and save. Secrets are encrypted at rest and never returned to the browser. If you share one Atlassian app with Jira, the Confluence integration is still its own row 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 Confluence.
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 adds every Confluence site the consent covered, 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

Each bullet starts with the message you see in Athena.

• “No enabled oauth2 Integration is registered for Confluence (Direct).” You clicked Connect before your workspace admin finished Step 2. Ask them to save the integration, 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…” Atlassian invalidates connections after 90 days of inactivity, on password changes, on SSO migrations, and when you revoke access at id.atlassian.com → Connected apps. Reconnecting fixes all of those. The message ends with “Confluence’s response: …” — if reconnecting does not clear it, read that part: it is Confluence’s own reason, such as a missing Confluence license or a page you are not allowed to see.
• “Confluence returned 404 — the page, space, or comment does not exist or is not visible to your Confluence user.” Confluence hides content you cannot see rather than reporting it: space listings show only the spaces you can view, searches skip restricted pages, and a page you cannot open looks like a page 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.” 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” — the app was installed on a site without Confluence, or only Jira was selected on the consent screen. Connect again and choose a site where Confluence Cloud is active.
  • “…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 your workspace admin to pin it: set connection.site_url on the Confluence integration (Workspace Settings → Treasury → Integrations) to your Confluence host, e.g. your-site.atlassian.net, and connect again. Athena then reaches the site directly and verifies the connection against Confluence before accepting it — if Confluence refuses, you get Confluence’s own error instead of a generic “no sites”.
• 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.

​

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.
• Athena has no admin-side revocation of another member’s connection. A workspace admin who needs a member’s Confluence access removed asks that member to remove the connection or to revoke it at id.atlassian.com.

​

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 Athena workspace. Atlassian refresh tokens are single-use, so two workspaces refreshing the same grant invalidate each other’s connection and both then have to reconnect.