Connect Confluence Cloud

This page describes how to connect Confluence Cloud to Agentspace Enterprise.

After you set up your data source and import data the first time, the data store syncs data from that source at a frequency that you select during setup.

Supported versions

The Confluence Cloud connector supports Confluence REST API versions v1 and v2.

Before you begin

Before you set up your connection:

1. Verify that you have administrator access to the Confluence instance and project.

2. To retrieve user email addresses from Confluence Cloud, even when settings restrict email visibility, install the User Identity Accessor for Confluence Cloud app. You must be a Confluence Site administrator to install and configure this app. After you install the app, configure it to securely retrieve user email addresses. You might not need to install this app if the email addresses are publicly accessible.

3. Set up access control for your data source. For information about setting up access control, see Use data source access control.

Set up authentication and permissions in Confluence

Make sure that you have the necessary authentication details and administrator access to your Confluence instance. Use the following instructions to create a client ID and client secret through the Atlassian Developer Console, configure the required OAuth 2.0 scopes, set up permissions for users, retrieve your instance URL and ID, configure roles, and authenticate to sync data between Confluence Cloud and Agentspace Enterprise. To enable OAuth 2.0 and obtain the client ID and secret, see OAuth 2.0 (3LO) apps in the Atlassian Developer documentation.

1. Create an OAuth 2.0 integration in the Atlassian Developer Console:

   1. Sign in to Atlassian Developer Console.

   2. Click the profile icon and select Developer console.

      

      Select Developer console

   3. Click Create and select OAuth 2.0 Integration.

      

      Select OAuth 2.0 Integration

   4. Enter a name for the app and do the following:

      1. Check the terms and conditions checkbox.

      2. Click Create.

         

         Create a new OAuth 2.0 Integration

      3. Click Authorization.

      4. In the Authorization type table, select Add for OAuth 2.0 (3LO).

         

         Add authorization type

   5. In the Callback URL field, enter https://vertexaisearch.cloud.google.com/console/oauth/confluence_oauth.html.

   6. Click Save changes.

      

      Save changes

If you see the warning: Your app doesn't have any APIs. Add APIs to your app, continue with the next procedure to configure OAuth 2.0. Otherwise, skip to step 4 in that procedure.

Note: Classic scopes are not available for Confluence Cloud connectors. Additionally, after adding the Confluence API, the Configure button may take a moment to appear. If it does not show up immediately, try refreshing the page or waiting a few seconds.

To configure OAuth 2.0 and retrieve the required credentials for your Confluence connector setup, do the following:

1. Enable OAuth 2.0:

   1. Click Permissions.

      

      Select permissions

   2. Go to Confluence API.

   3. Click Add.

   4. Click Configure.

   5. Go to the Granular scopes tab and click Edit scopes.

      

      Edit scopes

   6. Select the following scopes.

      • read:attachment:confluence
      • read:configuration:confluence
      • read:content.metadata:confluence
      • read:content-details:confluence
      • read:whiteboard:confluence
      • read:group:confluence
      • read:space:confluence
      • read:user:confluence

   7. Confirm that eight scopes are selected and save your changes.

2. Obtain the client ID and client secret:

   1. Click Distribution.

   2. Select Edit.

      

      Edit distribution

   3. Select Sharing to enable editing other fields.

   4. Fill out the remaining fields. Make sure to set Vendor name to Google and Privacy policy to https://policies.google.com.

   5. In the Personal data declaration section, do the following:

      1. In the Does your app store personal data? list, select Yes.

      2. To confirm that you have implemented Personal Data Reporting API, select the I confirm that I've implemented the Personal Data Reporting API checkbox.

      3. Click Save changes.

   6. Select Settings to copy your Client ID and Client secret.

      

      Copy your client ID and client secret

3. Obtain the instance URL:

   1. Go to atlassian.net and sign in with your administrator account.
   2. Select the app you want to sync. For example, sync the first app.
   3. Find the instance URL. It appears as the subdomain in the address bar.

4. Obtain the instance ID:

   1. Open a new tab, copy the instance URL, and append /_edge/tenant_info to the instance URL. For example, https://<var>YOUR-INSTANCE</var>.atlassian.net/_edge/tenant_info.

   2. Navigate to the link to find the cloudId value. The cloudId is your instance ID.

      

      Obtain instance ID

Token refresh

The default expiry time for a refresh token is 365 days. If your refresh token expires or is revoked, you can do one of the following:

• Reinitiate the OAuth flow.
• Use the refresh token to get a new access token and refresh token pair.

For more information, see Access token expires or is revoked.

Minimum administrator permissions

The following table lists the minimum administrator permissions required to create a Confluence Cloud connector:

Permission	Usage reason	Description
read:content-details:confluence	Data ingestion	Allows the connector to read content details in Confluence.
read:content.metadata:confluence	Data ingestion	Allows the connector to read content metadata.
read:space:confluence	Data ingestion	Allows the connector to read spaces.
read:whiteboard:confluence	Data ingestion	Allows the connector to read whiteboards.
read:attachment:confluence	Data ingestion	Allows the connector to read attachments.
read:configuration:confluence	Enforce ACLs	Enables enforcement of ACLs to access the Confluence site.
read:group:confluence	Enforce ACLs	Enables enforcement of ACLs to read user and group details.
read:user:confluence	Enforce ACLs	Enables enforcement of ACLs to read user details.

Set up an API token in Confluence

If you plan to use an API token for authentication, you must create an API token without scopes. This connector doesn't support API token with scopes.

1. Sign in to Atlassian Console.
2. Click Create API token.
3. Enter a name for the API token.
4. Select an expiration date for the API token. The token expiration period ranges from 1 to 365 days.
5. Click Create.
6. Save the token for later use.

Manage user visibility and grant roles

Note: For user permissions to apply correctly, each Confluence Cloud user must make their email visible to all users. To achieve this, change the email visibility settings in Confluence Cloud and set the visibility to Anyone.

To set the user visibility, do the following:

1. Click the user profile icon and go to Manage account.

   

   Manage account

2. Navigate to the Profile and visibility.

   

   Profile and visibility

3. Go to Contact and set the Who can see this as Anyone.

   

   Contact

To grant Confluence administrator with Discovery Engine Editor role in the Google Cloud console, do the following:

1. In the Google Cloud console, go to the IAM page.

   Go to IAM

2. Locate the Confluence administrator account.

3. Grant the Discovery Engine Editor role to the administrator.

To grant a user with an administrator role in Atlassian, do the following:

1. Sign in to Atlassian using an administrator account.

2. Click the menu icon and select your organization. Alternatively, you can go to admin.atlassian.com.

3. On the Apps page, click (the ellipsis icon) next to Confluence and select the Manage users button.

   

   Manage users

4. Click Groups under User management.

5. On the Groups page:

   1. Click Create group.
   2. Enter a name for the group.

   

   Create group

   This group receives permissions required by the connector. Users added to this group inherit these permissions. The connector uses this group to authenticate and fetch documents.

6. On the group page, click Add product.

   1. Select User access admin as the product role.

   2. Click Add.

      

      Confluence user access administrator

7. Click Add group members to add the user account or group members that the connector uses to authenticate.

   

   Add group members

Install the User Identity Accessor for Confluence Cloud app

To install the User Identity Accessor app on your Confluence Cloud site, follow these steps:

1. Navigate to Atlassian Developer Console.

2. Review the Read Email Address and App Storage scope permissions and click Get app.

   

   Review permissions and get app

3. From the Select a site to install this app on list, select the Confluence site where you want to install the app. This list displays only the sites for which you have administrator access.

   Note: You must be an administrator of at least one Confluence site to install the app.

4. Click Install to complete the app installation.

Configure the User Identity Accessor for Confluence Cloud app

After you've installated the User Identity Accessor for Confluence Cloud app, configure an API key that your external system (for example, your Confluence Cloud Connector) uses to securely call the app's webtrigger to fetch emails.

Access the configuration page

To access the User Identity Accessor app's configuration page in Confluence Cloud, follow these steps:

1. In your Confluence Cloud instance, click the Settings ⚙️ icon in the navigation menu.
2. Select Apps from the menu.
3. On the Apps administration page, locate your app, User Identity Accessor for Confluence Cloud, in the Manage apps list.

4. Click Configure or the link associated with your app. The app's dedicated configuration page opens within Confluence.

   

   Configure the User Identity Accessor for Confluence Cloud app

Set up the API key

To set up the API key on the configuration page, follow these steps:

1. In the API Key Configuration section, specify the secret key for authenticating requests to the app's webtrigger. You can authenticate requests using either of the following methods:

   • Enter your own key: Type or paste your own strong, unique API key into the API Key field. Use a key of at least 20–30 characters with a mix of uppercase letters, lowercase letters, numbers, and symbols.

     

     Enter your own key

   • Generate a key: Click the Generate New Key button. The system generates and displays a strong, random key in the field.

     

     Generate a key

     Important: Immediately copy the API key displayed in the field. For security reasons, you might be unable to view the full key again after saving or navigating away. If lost, you need to set or generate a new one.

2. Click Save API Key. A success message confirms that the key is securely saved.

Note: The API key generated or created in this section serves as the value for the Confluence Identity Sync Forge Client Secret field in the Advanced Options section during Connector setup.

Test the app configuration

Verify if the User Identity Accessor for Confluence Cloud app is configured correctly by sending request from your external system and confirming that user email addresses are returned successfully.

Get the webtrigger URL

1. On the Apps administration page, locate the Webtrigger URL section, which displays the unique URL specific to your Confluence site and this app installation:
   • Your external system must call this URL to request user emails.
   • The URL typically looks like: http://uuid/domain.net/x1/randomId. For example, https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/WEBTRIGGER_ID, where YOUR_INSTANCE_ID is your Confluence Cloud instance identifier and WEBTRIGGER_ID is the unique identifier for the webtrigger endpoint generated for your app.
2. Click the Copy URL button or copy the entire URL.

Configure your external system

• Configure your external system that needs to fetch Confluence user emails with the API key and webtrigger URL obtained in the previous steps.

  • Endpoint URL: The webtrigger URL you copied.
  • HTTP Method: POST

  • Required Headers:

    • Content-Type: application/json

    • X-Api-Key: YOUR_API_KEY

      Replace YOUR_API_KEY with the API key you set or generated in the Set up the API key section.

Example curl command

This example demonstrates calling the User Identity Accessor for Confluence Cloud webtrigger, which accepts an array of account IDs and returns the email addresses.

curl --location --request POST 'https://YOUR_INSTANCE_ID.hello.atlassian-dev.net/x1/ENDPOINT_PATH' \
--header 'X-Api-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
   "accountIds": [
       "ACCOUNT_ID_1",
       "ACCOUNT_ID_2"
   ]
}'

Replace:

• YOUR_INSTANCE_ID with your Confluence Cloud instance ID
• ENDPOINT_PATH with the API endpoint path
• YOUR_API_KEY with the API key you set or generated in the Set up the API key section
• ACCOUNT_ID with Atlassian account IDs you want to target

Expected response

[{"accountId":"ACCOUNT_ID_1","emailAddress":"EMAIL_ADDRESS_1"},
 {"accountId":"ACCOUNT_ID_2","emailAddress":"EMAIL_ADDRESS_2"}]

Replace:

• ACCOUNT_ID_X with actual Atlassian account IDs
• USER_EMAIL_X with user email addresses returned from your API call

Implement security best practices

To confirm the security of your API key, follow these recommendations:

• Store the API key securely within your Confluence Cloud Connector's configuration.
• Verify that all communication with the webhook URL occurs over HTTPS. This is the default for User Identity Accessor for Confluence Cloud webtriggers.

If you encounter any issues or have questions specific to the app functionality, contact the app vendor support.

Create a Confluence Cloud connector

Console

To use the Google Cloud console to sync data from Confluence Cloud to Agentspace Enterprise, follow these steps:

1. In the Google Cloud console, go to the Agentspace page.

   Agentspace

2. In the navigation menu, click Data stores.

3. Click Create data store.

4. On the Select a data source page, scroll or search for Confluence Cloud to connect your third-party source.

5. In the Specify the Confluence Cloud source for your data store page do the following:

   1. Select your authentication method:

      

      Enter the authentication details

      • To use OAuth for authentication, select OAuth 2.0 Client Credentials and then specify the instance URI, instance ID, client ID, and client secret.

        • Click Login, choose a site for the app.
        • Click Accept.

        

        Choose a site on which to use the app

      • To use API token for authentication, select API Token and then specify the instance URI, Confluence username, and API token.

   2. Click Continue.

6. (Optional) In the Advanced options section, do the following:

   1. To allowlist only a set of static IP addresses, select the Enable Static IP Addresses checkbox.
   2. To sync data starting from a particular date, choose a date in the Sync Since field.
   3. To apply rate limits on the queries that the connectors sends to the Confluence instance, in the Max QPS field, specify the maximum queries per second. The default value is 20 QPS. You can incrementally increase the QPS value based on the Confluence server's performance. Before you increase the QPS value, consider the following:
      • The existing load on the Confluence server.
      • The throughput of other third-party applications that are using the server.
   4. In the Confluence Identity Sync Forge URL field, enter the URL generated by the User Identity Accessor for Confluence Cloud app.
   5. In the Confluence Identity Sync Forge Client Secret field, enter the client secret configured in the User Identity Accessor for Confluence Cloud, which is the API key you generated or created in the Set up the API key section.

7. Select which entities to sync and click Continue.

   Note: When you sync the Page entity, the Live Doc content is also synced.

   

   Select entities to sync

8. Select the Sync frequency for Full sync and the Incremental sync frequency for Incremental data sync. For more information, see Sync frequency.

   If you want to schedule separate full syncs of entity and identity data, expand the menu under Full sync and then select Custom options.

   

   Setting separate schedules for full entity sync and full identity sync.

9. Select a region for your data connector.

10. Enter a name for your data connector.

11. Click Create. Agentspace Enterprise creates your data store and displays your data stores on the Data Stores page.

12. To check the status of your ingestion, go to the Data stores page and click your data store name to see details about it on its Data page. The Connector state changes from Creating to Running when it starts synchronizing data. When ingestion is complete, the state changes to Active to indicate that the connection to your data source is set up and awaiting the next scheduled synchronization.

    Depending on the size of your data, ingestion can take minutes or hours.

Error messages

The following table describes the common error messages, their descriptions, and possible solutions when connecting Confluence Cloud with Agentspace Enterprise.

Error code	Error message	Description	Troubleshooting
CONFLUENCE_INVALID_AUTHENTICATION_1	Authentication error. More information:	The connector cannot authenticate with Confluence Cloud.	Re-authenticate the data store with administrator credentials.
CONFLUENCE_INVALID_AUTHORIZATION_1	Authorization error. More information:	A user account without administrator privileges attempted to access Confluence Cloud.	Re-authenticate the data store using administrator credentials.
CONFLUENCE_TOO_MANY_REQUEST	Too many 429 HTTP Requests to Confluence Cloud.	The number of requests that the connector sent exceeds the default QPS value.	If this issue persists, reduce the QPS value of the data store using the Max QPS field.

Known limitations

• The legacy user management model is not supported for integration with Confluence Cloud. Only the centralized user management model is supported. For more information, see Atlassian organization consolidation guide
• This connector doesn't support incremental sync for the spaces entity.

Next steps

• To attach your data store to an app, create an app and select your data store following the steps in Create an app.

• To preview how your search results appear after your app and data store are set up, see Preview search results. If you used third-party access control, see Preview results for apps with third-party access control.

• To enable alerts for the data store, see Configure alerts for third-party data stores.