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

​
OAuth

If the credential screen shows Authorize with Confluence, select it. Approve the Atlassian consent screen, then choose the Confluence site. Hymalaia stores a refresh token and renews short-lived access tokens automatically. Use an API token when the authorize button is not available.

​
Atlassian API token

You can create an unscoped token or a scoped token. Atlassian recommends scoped tokens. Hymalaia supports both, but the Hymalaia 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 Hymalaia:
  • 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 Hymalaia 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 Hymalaia.

​
Add the Cloud credential to Hymalaia

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 Hymalaia Confluence credential dialog For both token types, Hymalaia uses the account email and token as HTTP Basic authentication. With a scoped token, Hymalaia 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 Hymalaia 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 Hymalaia Enterprise Edition. 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 Hymalaia 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 Hymalaia, 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.