> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Confluence Cloud

> Connect an Atlassian-hosted Confluence site to Onyx

Use this guide when Atlassian hosts your Confluence site. Its URL normally ends in `atlassian.net/wiki`.

## Before you begin

Use a dedicated Atlassian account for the connector. This keeps its access stable when employees change roles or leave.
Grant the account product access and view access to every space and restricted page that you want to index.
An API token never gives the account more access than it has in Confluence.

For details,
see Atlassian's [Confluence Cloud permission
model](https://support.atlassian.com/confluence-cloud/docs/what-are-confluence-cloud-permissions-and-restrictions/)
and [page restriction guide](https://support.atlassian.com/confluence-cloud/docs/add-or-remove-page-restrictions/).

## Choose an authentication method

### Onyx Cloud OAuth

If the credential screen shows **Authorize with Confluence**, select it. Approve the Atlassian consent screen,
then choose the Confluence site. Onyx stores a refresh token and renews short-lived access tokens automatically.

OAuth is the simplest option on Onyx Cloud. It is not the standard credential path for self-hosted Onyx.
Use an API token for self-hosted Onyx or when the authorize button is not available.

### Atlassian API token

You can create an unscoped token or a scoped token. Atlassian recommends scoped tokens. Onyx supports both,
but the Onyx checkbox must match the token type.

<Steps>
  <Step title="Open Atlassian account security">
    Sign in as the connector account and open [Atlassian account API
    tokens](https://id.atlassian.com/manage-profile/security/api-tokens).

    <img
      src="https://mintcdn.com/danswer/zePIWdUvZoTqQwQl/assets/admins/connectors/confluence/atlassian-api-tokens.jpg?fit=max&auto=format&n=zePIWdUvZoTqQwQl&q=85&s=f970c1bc57ff6a41762ea3366a1e4f14"
      alt="The Atlassian API Tokens page shows separate buttons for standard and scoped
tokens"
      width="780"
      height="220"
      data-path="assets/admins/connectors/confluence/atlassian-api-tokens.jpg"
    />
  </Step>

  <Step title="Create the token">
    Choose the button for your token type:

    * For a scoped token, select **Create API token with scopes**. Choose Confluence, set an expiration date,
      and add the read scopes in the next step.
    * For an unscoped token, select **Create API token** and set a label.

    Atlassian API tokens expire after 1 to 365 days.
    Record the expiration date and plan to replace the token before it expires.
    See Atlassian's [API token
    instructions](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).
  </Step>

  <Step title="Grant scoped-token access">
    For a scoped token, grant the equivalent Confluence read access used by Onyx:

    * `read:confluence-space.summary`
    * `read:confluence-props`
    * `read:confluence-content.all`
    * `read:confluence-content.summary`
    * `read:confluence-content.permission`
    * `read:confluence-user`
    * `read:confluence-groups`
    * `read:space:confluence`
    * `readonly:content.attachment:confluence`
    * `search:confluence`
    * `read:attachment:confluence`
    * `read:content-details:confluence`

    These scopes let Onyx read spaces, pages, comments, attachments, restrictions, users, and groups.
    They do not override the connector account's Confluence permissions.
    See Atlassian's [Confluence scope
    reference](https://developer.atlassian.com/cloud/confluence/scopes-for-oauth-2-3LO-and-forge-apps/).

    <img
      src="https://mintcdn.com/danswer/zePIWdUvZoTqQwQl/assets/admins/connectors/confluence/atlassian-scopes.jpg?fit=max&auto=format&n=zePIWdUvZoTqQwQl&q=85&s=ad6f5adb5009582555f4cf4e249be5d9"
      alt="Atlassian's Confluence scope picker filtered to read
scopes"
      width="1728"
      height="815"
      data-path="assets/admins/connectors/confluence/atlassian-scopes.jpg"
    />

    The screenshot shows some read scopes. Select every scope in the list above.
  </Step>

  <Step title="Copy the token">
    Create and copy the token. Atlassian shows the token value once.
    Store it in your secrets manager until you add it to Onyx.
  </Step>
</Steps>

## Add the Cloud credential to Onyx

Open **Admin Panel > Connectors > Confluence**, select **Create New**, and enter:

* **Name**: A clear name, such as `Confluence Cloud - docs account`.
* **Confluence Username**: The connector account's Atlassian email address.
* **Confluence Access Token**: The API token.

<img src="https://mintcdn.com/danswer/zePIWdUvZoTqQwQl/assets/admins/connectors/confluence/credential-form.jpg?fit=max&auto=format&n=zePIWdUvZoTqQwQl&q=85&s=befd37d583413a4ba7ad62493a53cbe0" alt="The Onyx Confluence credential dialog" width="1728" height="871" data-path="assets/admins/connectors/confluence/credential-form.jpg" />

For both token types, Onyx uses the account email and token as HTTP Basic authentication. With a scoped token,
Onyx directs Confluence API requests through Atlassian's API gateway.

## Configure the Cloud connector

Select the credential, select **Continue**, and configure these fields:

* Enable **Is Cloud**.
* Set **Wiki Base URL** to `https://your-domain.atlassian.net/wiki`. Keep `/wiki` in the URL.
* Enable **Using scoped token** only when you created the token with scopes.
* Choose the indexing scope and attachment setting described in the [Confluence overview](./confluence).

<img
  src="https://mintcdn.com/danswer/zePIWdUvZoTqQwQl/assets/admins/connectors/confluence/connector-form-cloud.jpg?fit=max&auto=format&n=zePIWdUvZoTqQwQl&q=85&s=748efe7dac1cc637e44c87e9eca9f0ef"
  alt="A Confluence Cloud connector configured in Onyx with an unscoped
token"
  width="1728"
  height="871"
  data-path="assets/admins/connectors/confluence/connector-form-cloud.jpg"
/>

This example uses an unscoped token. Enable **Using scoped token** if you created a scoped token.

## Configure Cloud permission sync

Permission sync requires Onyx Enterprise Edition or Onyx Cloud. It reads space permissions, page restrictions,
inherited ancestor restrictions, users, groups, and group membership.

Before you enable it:

* Use a Confluence administrator account, or make the connector account a space administrator for every indexed space.
* Keep the permission-related token scopes from the scoped-token list.
* Confirm that user email addresses are visible to the connector account. Atlassian users control this under **Manage
  account > Profile and visibility > Contact**.
  See Atlassian's [email visibility
  guide](https://support.atlassian.com/confluence-cloud/docs/configure-user-email-visibility/).
* Confirm that each Confluence email matches the user's Onyx email.

<Warning>
  Do not enable permission sync until you test a public space, a restricted space, a restricted page,
  and a page below a restricted ancestor.
  Missing emails or incomplete group visibility can prevent expected users from finding content.
</Warning>

## Rotate a Cloud token

Create a replacement token before the old token expires. In Onyx, edit or replace the credential used by the connector,
then run a new indexing attempt. Revoke the old token only after the new credential succeeds.