# Atlassian Confluence Cloud knowledge base integration
Use the Atlassian Confluence Cloud knowledge base integration to index Confluence content so that Amazon Quick agents can search and answer questions about it. Amazon Quick supports optional document-level access controls (ACLs) for Confluence knowledge bases. When enabled, users only see answers from documents they are authorized to access in Confluence. For more information, see [Document-level access controls](confluence-kb-acl.md).
## Before you begin
Make sure you have the following before you set up the integration.
+ An Atlassian Confluence Cloud instance.
+ For Quick subscription requirements, see [Set up integrations in the console](integration-console-setup-process.md).
If you plan to enable document-level access controls, you must provide Atlassian admin credentials during setup. These credentials allow Amazon Quick to access all user and group information regardless of individual email visibility settings. Without admin credentials, the ACL option is not available during knowledge base creation. To provide admin credentials, you need the following from your Atlassian organization administrator:
+ **Atlassian admin API key** – An alphanumeric string generated in the Atlassian admin portal.
+ **Organization ID (UUID)** – The unique identifier for your Atlassian organization. You can find this in your browser URL when signed in to the admin portal: `admin.atlassian.com/o/orgId`.
+ **Directory ID (UUID)** – The unique identifier for your user directory. Retrieve this value using the Atlassian Admin Workspace API.
For detailed steps to obtain these credentials, see [Obtain Atlassian admin credentials](confluence-kb-acl.md#confluence-kb-atlassian-admin-credentials).
## Set up the knowledge base integration
The setup wizard has three steps: authentication, knowledge base creation, and additional settings.
### Authenticate your account
1. In the Amazon Quick console, choose **Integrations**.
1. Under **Knowledge**, choose **Atlassian Confluence Cloud** and choose the Add (plus "\$1") button.
1. In the **Create Confluence knowledge base** dialog, under **Authentication method**, choose an existing connected account from the **Name** dropdown, or choose **Add account** to create a new connection.
1. If you are adding a new account, complete the following fields:
+ **Name** – A descriptive name for your connection.
+ **Description** (Optional) – Notes about the connection.
+ **Confluence URL** – The URL of your Atlassian site (for example, `https://your-site.atlassian.net`).
1. (Optional) Under **ACL Management**, select **Use Atlassian admin credentials** to provide Atlassian admin credentials. When selected, enter the following:
+ **API key** – The Atlassian admin API key.
+ **OrganizationID (UUID)** – Your Atlassian organization ID.
+ **Directory ID (UUID)** – Your Atlassian user directory ID.
**Important**
Atlassian admin credentials are required to enable document-level access controls (ACLs) in **Additional settings**. Without admin credentials, the ACL option is disabled. Admin credentials cannot be added after the knowledge base is created. For steps to obtain these credentials, see [Obtain Atlassian admin credentials](confluence-kb-acl.md#confluence-kb-atlassian-admin-credentials).
1. Choose **Next**.
1. Complete the Confluence Cloud authentication popup that appears. Review the requested permissions and choose **Accept** to authorize Amazon Quick to access your Confluence content.
### Create the knowledge base
1. Under **Create knowledge base**, enter a **Name** for your knowledge base.
1. (Optional) Enter a **Description** with notes about how the knowledge base will be used.
1. Under **Confluence URLs**, paste the URLs of the Confluence spaces, blogs, or pages that you want to include. Choose **Add** after each URL.
**Note**
URLs that follow the structure `https://company.atlassian.net/wiki/spaces/space-key/overview` are treated as page URLs, not space URLs. To index an entire space, use the space URL without `/overview` (for example, `https://company.atlassian.net/wiki/spaces/space-key`).
1. Choose **Next: Additional settings** to configure access controls and indexing options, or choose **Create** to create the knowledge base with default settings.
### Configure additional settings
1. To enable document-level access controls, select **Control document access with ACLs**. This option is only available if you provided Atlassian admin credentials in **Authentication method**. When enabled, Amazon Quick syncs access control lists from Confluence and verifies each user's permissions at query time. For more information about how access controls work, see [Document-level access controls](confluence-kb-acl.md).
If you do not enable ACLs, access is controlled at the knowledge base level. Anyone who has access to the knowledge base can get insights from all of the content within it. When ACLs are enabled, access is controlled at the document level. Users who have access to the knowledge base only see answers from documents that they are authorized to access in Confluence.
**Important**
ACL management cannot be changed after the knowledge base is created. If you need to change this setting, you must create a new knowledge base.
**Note**
If you did not provide Atlassian admin credentials in **Authentication method**, this option is disabled. To enable ACLs, choose **Back** or cancel the wizard and start again with a connected account that includes admin credentials.
1. Under **Multi-media content, file size, and file patterns**, configure the following indexing options as needed:
+ **Visual content in documents** – Index visual content such as images and charts embedded in documents.
+ **Audio files** – Index audio file attachments.
+ **Video files** – Index video file attachments.
+ **Maximum single file size** – The maximum file size for individual attachments (default: 50 MB).
1. Choose **Create**.
## Supported content types
+ Confluence pages and blog posts
+ Page and blog post attachments
When you add a Confluence space URL, Amazon Quick crawls all pages and blog posts within that space. For supported attachment file types and size limits, see [File size and content limits](knowledge-base-integrations.md#file-size-and-content-limits).
## Manage knowledge bases
### Edit existing knowledge bases
1. In the Amazon Quick console, choose **Knowledge bases**.
1. Select your Confluence Cloud knowledge base from the list.
1. Choose the three-dot icon under **Actions**, then choose **Edit knowledge base**.
1. Update your configuration settings as needed and choose **Save**.
## Troubleshoot
To edit, share, or delete your integration, see [Managing existing integrations](integration-workflows.md#managing-existing-integrations).
For general knowledge base troubleshooting, including sync issues and missing documents, see [Troubleshooting knowledge bases](troubleshooting-knowledge-bases.md).
### Blocked OAuth app authorization
**Symptoms:**
+ Error message: "Your site admin must authorize this app for the site *instance-name*.atlassian.net before the app can access your account."
+ Choosing **Accept** in the consent dialog has no effect.
**Cause:**
Your Atlassian site administrator has blocked user-installed OAuth apps. When this setting is enabled, only a site or organization administrator can authorize new third-party apps.
**Resolution steps:**
Use one of the following options to resolve this issue.
+ **Option 1 (Recommended): Admin authorizes the app directly**
1. An Atlassian site administrator navigates to Amazon Quick and starts a new knowledge base setup with Confluence Cloud.
1. Because the administrator has site-level permissions, a clean consent screen appears without the error.
1. The administrator chooses **Accept** to install the app.
After the administrator authorizes the app, all other users on the site can connect without issues.
+ **Option 2: Temporarily allow user-installed apps** – An administrator goes to `admin.atlassian.com`, navigates to **Apps**, **Atlassian Apps**, then chooses the link for third-party and Marketplace apps. Under **Settings**, find **User Installed Apps** and toggle to allow user apps. After the user authorizes Amazon Quick, toggle the setting back to block user apps.
**Important**
Admin authorization applies per Atlassian site, not per organization. If your company has multiple sites (for example, `team-a.atlassian.net` and `team-b.atlassian.net`), each site requires separate authorization.
**Note**
While user-installed apps are unblocked (Option 2), any user on the site can authorize any OAuth app. Re-enable the block promptly after the user has connected.
### Authentication popup fails
**Symptoms:**
+ Authentication popup does not appear or closes immediately.
+ Popup appears but fails to complete the OAuth flow.
**Resolution steps:**
1. Verify that your browser allows popups from the Amazon Quick console domain.
1. Verify that your Confluence Cloud instance is accessible from your network.
1. Try using a different browser or clearing your browser cache.
### Missing content in knowledge base
**Symptoms:**
+ Knowledge base sync completes but expected content is not indexed.
+ Search results do not include content from specific spaces or pages.
+ Only one document is indexed for an entire space.
**Resolution steps:**
1. Verify that the Confluence Cloud user who authenticated has access to the spaces and pages you selected during setup.
1. Check that the selected content types are supported (pages, blog posts, and attachments).
1. Review the content selection in your knowledge base configuration to confirm the correct spaces and pages are included.
1. Check your Confluence URLs for the `/overview` suffix. URLs that end with `/wiki/spaces/space-key/overview` are treated as a single page URL, not a full space. If you intended to index the entire space, use the space URL without `/overview` (for example, `https://company.atlassian.net/wiki/spaces/space-key`).
### ACL-related issues
**No results from ACL-enabled knowledge base**
+ Verify that the end user has signed in to Confluence when prompted during their first query. The sign-in is required for real-time permission verification.
+ Verify that the end user has access to the relevant Confluence content in their Confluence instance.
**Documents skipped during sync**
+ If sync reports show items with status SKIPPED, verify that the authenticating user has access to the Confluence spaces and pages included in the knowledge base.
+ For more information about verifying document access, see [Check document access (ACL verification)](sync-reports-observability.md#sync-reports-acl-verification).
# Document-level access controls
Confluence Cloud knowledge bases optionally support document-level access control. When enabled, Amazon Quick syncs access control lists (ACLs) from Confluence during each crawl and verifies each user's permissions at query time. Users only see answers from documents they are authorized to access in Confluence.
## How it works
When a user queries an Amazon Quick agent that uses a Confluence knowledge base with ACL management enabled, the system enforces access controls in two stages:
1. **Pre-retrieval filtering** – Amazon Quick performs a semantic search against the vector index to find the most relevant document passages. The system applies access control lists that were synced from Confluence during the last crawl. This produces a preliminary set of candidate documents.
1. **Real-time verification** – The system verifies the candidate documents in real time by checking the querying user's current access in Confluence. Only documents the user is currently authorized to access appear in the response.
This two-stage approach provides document-level access control that stays current even when Confluence permissions change between syncs.
Amazon Quick crawls the following Confluence ACL resources:
+ **Spaces** – Space permissions apply to all documents in the space by default.
+ **Pages** – Pages can be restricted to specific users and groups. Nested pages inherit restrictions from the parent page and can have their own restrictions.
+ **Blogs** – Blog posts can be restricted to specific users and groups in the space.
+ **Attachments** – Files attached to pages or blog posts inherit the access controls of their parent document.
## Enable ACL management
You configure ACL management during knowledge base creation in the **Additional settings** step. Select the **Control document access with ACLs** checkbox to enable it. This option requires Atlassian admin credentials, which you provide during the **Authentication method** step. Without admin credentials, the ACL option is disabled.
**Important**
You cannot change ACL management after you create the knowledge base. If you need to change this setting, you must create a new knowledge base.
Atlassian admin credentials allow Amazon Quick to access all user and group information from your Confluence instance, regardless of individual email visibility settings. For steps to obtain admin credentials from your Atlassian organization, see [Obtain Atlassian admin credentials](#confluence-kb-atlassian-admin-credentials). For the knowledge base setup steps, see [Authenticate your account](confluence-knowledge-base.md#confluence-kb-setup-auth).
For more information about ACL best practices, see [Best practices for managing ACLs in knowledge bases](acl-best-practices-kb.md).
## Real-time access verification
When a user submits a query that involves content from an ACL-enabled Confluence knowledge base, Amazon Quick verifies the user's access in real time:
1. The user asks a question in the Quick chat assistant.
1. If the answer involves Confluence content from an ACL-enabled knowledge base, Quick prompts the user to sign in to Confluence.
1. The user signs in with their Confluence email and password and accepts the authorization dialog.
1. Quick uses the user's credentials to verify access to each candidate document in real time against the Confluence API.
1. Only documents the user currently has access to in Confluence appear in the response.
The sign-in is a one-time step. After signing in, users are not prompted again until their session expires.
**Note**
If real-time permission verification fails (for example, if the Confluence API is temporarily unavailable), users see an error message prompting them to retry. Amazon Quick does not fall back to cached permissions — real-time verification is mandatory to ensure access control accuracy.
## Obtain Atlassian admin credentials
To provide Atlassian admin credentials during Confluence knowledge base setup, your Atlassian organization administrator must complete the following steps.
### Get your API key and Organization ID
1. Sign in to the [Atlassian admin portal](https://admin.atlassian.com/) with administrator permissions.
1. Open the Administration app for your organization. The URL should look like: `https://admin.atlassian.com/o/ORGANIZATION-UUID/overview`.
1. Copy the **Organization ID** from the URL.
1. Choose **Settings**, then choose **API Keys**.
1. Choose **Create API key**.
1. Select the following scopes for the API key:
+ `read:directories:admin`
+ `read:workspaces:admin`
1. Copy and save both the **Organization ID** and **API Key**.
**Note**
API keys expire. Monitor the expiration date and update your data source credentials before the key expires.
### Get your Directory ID
Use the Atlassian Admin Workspace API to retrieve your Directory ID.
1. Run the following command, replacing *ORGANIZATION-ID* with your Organization ID and *API-KEY* with your API key:
```
curl --request POST \
--url 'https://api.atlassian.com/admin/v2/orgs/ORGANIZATION-ID/workspaces' \
--header 'Authorization: Bearer API-KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"query": {
"field": {
"name": "attributes.type",
"values": ["confluence"]
}
},
"limit": 20
}'
```
This query filters results to Confluence workspaces only, so you don't need to page through all workspace types.
1. In the API response, find the workspace entry that matches your Confluence Cloud instance. Verify the workspace name matches your instance.
1. Copy the `directory` value from the `attributes` section. This is your **Directory ID**.
For more information about Atlassian admin API scopes, see [Atlassian API scopes documentation](https://developer.atlassian.com/cloud/admin/scopes/). For API details, see [Atlassian Admin Workspace API reference](https://developer.atlassian.com/cloud/admin/organization/rest/api-group-workspaces/#api-group-workspaces).
## Limitations
+ **Atlassian admin credentials required** – Document-level access controls require Atlassian admin credentials, which must be provided during knowledge base setup. You cannot enable ACLs without admin credentials, and you cannot add admin credentials after the knowledge base is created.
+ **Real-time verification is mandatory** – Amazon Quick always performs real-time permission checks at query time for ACL-enabled knowledge bases. If the Confluence API is unavailable, queries that involve ACL-protected content return an error rather than falling back to cached permissions.
For general ACL limitations and best practices, including ACL permanence, research compatibility, and email address management, see [Best practices for managing ACLs in knowledge bases](acl-best-practices-kb.md).
## Next steps
To verify document-level access controls and troubleshoot permission issues, see [Check document access (ACL verification)](sync-reports-observability.md#sync-reports-acl-verification). For information about setting up the Confluence knowledge base integration, see [Set up the knowledge base integration](confluence-knowledge-base.md#confluence-kb-setup).