---
doc_version: "1.0.0"
last_updated: "2026-09-09T14:42:47.940Z"
title: "How to connect Confluence"
description: "Connect a Confluence Cloud wiki to ChatbotIQ using an Atlassian API token. Works with SSO, syncs only the spaces you choose, and re-indexes only pages that changed."
keywords: [Confluence, Atlassian, API token, SSO, wiki, knowledge base, scoped token, ChatbotIQ]
---

ChatbotIQ reads Confluence Cloud through the Atlassian API rather than crawling it in a browser. That matters for two reasons:

- **SSO is not a blocker.** Atlassian API tokens bypass SAML, so wikis with anonymous access turned off work fine. This is the recommended way to index Confluence.
- **Syncs stay cheap.** Confluence reports a version number per page, so a repeat sync only re-reads pages someone actually edited.

If you previously added your wiki as a website source, switch it to a Confluence source. You will get cleaner content, page hierarchy in search, and much faster refreshes.

## Before you start

You need:

- A **Confluence Cloud** site (`your-site.atlassian.net`). Self-hosted Data Center is not supported yet.
- An Atlassian account that can see the spaces you want to index.
- Admin or owner role in your ChatbotIQ workspace.

### Create a service account first

Read this before creating a token. It is the difference between a safe setup and one that quietly leaks internal pages.

**An Atlassian API token inherits every permission of the account that created it.** If you create a token on your own admin account, ChatbotIQ can read every page you can see, including HR, legal, and restricted spaces. If that bot is public-facing, those pages can end up in answers.

So:

1. Create a **dedicated Atlassian account** for ChatbotIQ (for example `chatbotiq@your-company.com`).
2. Grant it view access to **only** the spaces you intend to index.
3. Create the API token on that account, not on your own.

## Step 1: Create a scoped API token

Atlassian supports **scoped** tokens, which grant only the permissions you list instead of everything the account can do. Use one.

1. Go to [Atlassian API tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
2. Choose **Create API token with scopes**.
3. Select your Confluence site.
4. Select exactly these three scopes, and nothing else:

   | Scope | Why it is needed |
   |---|---|
   | `read:space:confluence` | List your spaces so you can pick which to index |
   | `read:page:confluence` | List the pages in those spaces |
   | `read:content-details:confluence` | Read page content |

5. Set an expiry date and **write it down**. You will need it in Step 2.
6. Copy the token. Atlassian shows it once.

> **Every Atlassian token expires.** The maximum lifetime is 365 days, and there is no way to create a permanent one. When the token expires, syncing stops. Tell ChatbotIQ the expiry date in the next step and we will remind you before that happens.

## Step 2: Connect the site

1. In ChatbotIQ, open **Knowledge Base** and click **Add source**.
2. Choose **Confluence**.
3. Fill in:
   - **Confluence site**: `https://your-site.atlassian.net` (or just the site name)
   - **Atlassian account email**: the service account's email
   - **API token**: the token from Step 1
   - **Token expiry date**: from Step 1
4. Click **Connect**.

ChatbotIQ verifies the credentials immediately. If they are wrong or the scopes are insufficient, you will see an error here rather than an empty sync later.

Your token is encrypted before it is stored, and no ChatbotIQ screen or API response ever shows it again. You will only see the last four characters.

## Step 3: Choose spaces and sync

After connecting, you will see every space the token can read.

**Select only the spaces you want your bot to answer from.** This list is the main control against indexing more than you meant to. ChatbotIQ reads nothing outside it, and the restriction is enforced on the server, not just in the interface.

Give the source a name, then click **Start sync**.

The first sync reads every page in the selected spaces. Large wikis take a while; you can close the wizard and the sync continues in the background.

## What gets indexed

For each page ChatbotIQ stores the title, the content, and its place in the wiki:

- **Page hierarchy** becomes a breadcrumb (`Operations > Runbooks > Deployment Runbook`), which improves how well the bot matches questions to pages.
- **Real page URLs**, so answers cite a clickable link to the wiki page.
- **Last edited date** from Confluence, not the sync time.

Tables, code blocks, and lists are preserved. Attachments and images are not indexed yet.

## Keeping content up to date

Run a sync whenever you want to pick up changes. Repeat syncs are cheap: ChatbotIQ compares each page's Confluence version number and only re-reads pages that changed. A sync of an unchanged wiki uses no indexing credits.

Pages that are deleted, archived, or moved out of a selected space are removed from your bot's answers on the next sync.

## Troubleshooting

**"Confluence rejected the credentials"**
The token has expired or been revoked. Create a new one and reconnect. Remember the 365-day maximum.

**"The token is missing a required scope"**
The token is missing one of the three scopes in Step 1. Scoped tokens cannot be edited after creation, so create a new one.

**"This token cannot see any spaces"**
The service account has not been granted access to any space. Add it to the spaces you want indexed in Confluence's space permissions.

**A space is missing from the list**
The service account cannot see it. Grant it view permission on that space in Confluence.

**Some pages are missing after a sync**
Confluence page restrictions apply to the service account too. A page restricted from that account is invisible to ChatbotIQ, which is usually what you want.

**"Only Confluence Cloud sites are supported"**
You entered something other than a `*.atlassian.net` address. Self-hosted Confluence Data Center is not supported yet.

## Related

- [Source types](/reference/source-types/)
- [Build a Knowledge Bot for Confluence](/tutorials/build-an-internal-knowledge-bot/)
- [Keep content up to date](/how-to/refresh-and-maintain-sources/)

## Sitemap

Full documentation index: [sitemap.md](/sitemap.md) and [llms.txt](/llms.txt).