Skip to main content
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 and page restriction guide.

​
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.
1

Open Atlassian account security

Sign in as the connector account and open Atlassian account API tokens.The Atlassian API Tokens page shows separate buttons for standard and scoped tokens
2

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.
3

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.Atlassian's Confluence scope picker filtered to read scopesThe screenshot shows some read scopes. Select every scope in the list above.
4

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.

​
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.
The Onyx Confluence credential dialog 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.
A Confluence Cloud connector configured in Onyx with an unscoped token 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.
  • Confirm that each Confluence email matches the user’s Onyx email.
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.

​
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.