> ## Documentation Index
> Fetch the complete documentation index at: https://resources.athenaintel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Setup is two steps, done by two different people: your **Atlassian
administrator** registers an OAuth app in the Atlassian developer console,
then an **Athena workspace admin** saves that app once for the whole
workspace. Members can only connect after both are done.
## 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.
**Already registered an Athena app for Jira?** One Atlassian app can hold
both the Jira API and the Confluence API permissions, but Confluence uses its
own callback URL and Atlassian's console has historically accepted only one
callback URL per app. If your console lets you add a second callback URL,
open the existing app, add the Confluence scopes from step 3 and the callback
URL from step 4, and reuse its Client ID and Secret in Step 2. Otherwise,
register a separate app for Confluence by following the steps below.
1. Open **[developer.atlassian.com](https://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:
```text theme={null}
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:
```text theme={null}
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.
If your Atlassian organization uses the **"Block user apps"** security
control, an Atlassian org admin must authorize the app (Atlassian
Administration → Apps → Connected apps) before members can consent —
otherwise the consent screen shows an admin-approval notice and never
returns to Athena.
## Step 2 — Enable Confluence in Athena (workspace admin, once)
Open **[Workspace Settings → Treasury →
Integrations](https://app.athenaintel.com/dashboard/workspace-settings/treasury/?tab=integrations)**
and add a new integration:
| Field | Value |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| **Provider** | `confluence_direct` |
| **Auth method** | `oauth2` |
| **Config** | Pre-filled with Atlassian's authorize/token endpoints — paste the **Client ID** into `connection.client_id` |
| **Client Secret** | From step 1.6 (write-only — leave blank when editing to keep the current one) |
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](https://app.athenaintel.com/dashboard/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](https://id.atlassian.com/manage-profile/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](https://id.atlassian.com/manage-profile/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](https://id.atlassian.com/manage-profile/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.