> For the complete documentation index, see [llms.txt](https://herd-security.gitbook.io/herd-security-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://herd-security.gitbook.io/herd-security-docs/policies/confluence-integration.md).

# Confluence Integration

Connect your Confluence Cloud site to Herd with your own Atlassian OAuth app, then link policies to live Confluence pages so Herd keeps them in sync instead of you re-uploading documents.

If your policies live in Confluence Cloud, you can link a Herd policy directly to a Confluence page instead of uploading a copy. Herd reads the page through an Atlassian OAuth app that you register, indexes its content so Herd AI answers from the live document, and re-reads every linked page daily so the indexed copy tracks edits made in Confluence. Access is **read-only**; Herd never modifies your pages.

Setup has three parts. Expect it to take about ten minutes.

1. [Register an Atlassian OAuth app](#part-1-register-an-atlassian-oauth-app) in the Atlassian developer console.
2. [Connect the app in Herd](#part-2-connect-the-app-in-herd).
3. [Link policies to Confluence pages](#part-3-link-policies-to-confluence-pages).

## Before you start

* You are a Herd admin with Integrations permissions.
* You have an Atlassian account that can open the [Atlassian developer console](https://developer.atlassian.com/console/myapps/) and can read the Confluence pages you plan to link. Herd reads pages **as that account**, so a page it cannot see cannot be indexed.
* Your site is **Confluence Cloud** (a `*.atlassian.net` address). Self-hosted Confluence Data Center and Server are not supported, because the OAuth flow Herd uses only exists in Cloud.

{% hint style="warning" %}
Use the **same Atlassian account** for both parts of the setup. An Atlassian OAuth app is private by default, which means only the account that created it can authorize it. If a different person will click **Connect to Confluence** in Herd, see [Letting another account authorize the app](#letting-another-account-authorize-the-app).
{% endhint %}

## Part 1: Register an Atlassian OAuth app

### Step 1: Open the Confluence tile in Herd

In Herd, go to **Settings → Integrations** and open the **Confluence** card (in the **Knowledge & Policies** section). Keep this tab open. The tile shows two values you will paste into the Atlassian developer console:

* **Callback URL (paste into your Atlassian app)**. Use the copy button next to it. The URL is specific to your Herd environment, so always copy it from the tile rather than from this page.
* **Required scopes**. Use the copy button next to them. The full list is:

```
offline_access read:confluence-content.summary read:confluence-content.all read:confluence-space.summary search:confluence
```

### Step 2: Create the app

1. Open the [Atlassian developer console](https://developer.atlassian.com/console/myapps/) and sign in.
2. Click **Create** and choose **OAuth 2.0 integration**.
3. Enter a name your team will recognise, such as *Herd Security*.
4. If Atlassian asks you to choose a grant type, choose **Resource-level**. Herd connects one Confluence site per organization, and Resource-level lets you pick that site on the consent screen. Account-level would grant every site in your Atlassian account, and Herd would connect whichever site came back first.
5. Accept Atlassian's developer terms and click **Create**.

### Step 3: Add the callback URL

1. In the app's left menu, click **Authorization**.
2. In the **OAuth 2.0 (3LO)** row, click **Add** (or **Configure** if you have been here before).
3. Paste the callback URL you copied from the Herd tile into **Callback URL**, exactly as shown. No trailing slash, no extra characters.
4. Click **Save changes**.

### Step 4: Add the Confluence permissions

1. In the left menu, click **Permissions**.
2. In the **Confluence API** row, click **Add**, then **Configure**.
3. Open the **Granular scopes** tab and add each of these four scopes. The list is long, so use the search box.
   * `read:confluence-content.summary`
   * `read:confluence-content.all`
   * `read:confluence-space.summary`
   * `search:confluence`
4. Click **Save**.

{% hint style="info" %}
`offline_access` is not a Confluence API scope, so you will not find it in this list. Herd requests it automatically when you authorize, and Atlassian grants it to any OAuth 2.0 (3LO) app. It is what lets Herd renew its access after the first hour; without it the connection would stop working after about an hour.
{% endhint %}

### Step 5: Copy the client ID and secret

1. In the left menu, click **Settings**.
2. Copy the **Client ID**.
3. Under **Secret**, click **Show** (or **Copy**) and copy the secret.

Treat the secret like a password. Herd encrypts it at rest and never displays it again after you save it.

## Part 2: Connect the app in Herd

### Step 1: Save the credentials

Back on the **Confluence** tile in **Settings → Integrations**, paste the values into **Atlassian OAuth client ID** and **Atlassian OAuth client secret**, then click **Save credentials**.

### Step 2: Authorize Herd

1. Click **Connect to Confluence**. Herd opens Atlassian's consent screen.
2. If your account has access to more than one Atlassian site, pick the Confluence site you want to connect.
3. Review the requested access and click **Accept**.

Atlassian sends you back to **Settings → Integrations**. The Confluence tile now shows the name of the connected site and when the connection was last checked. Click **Check connection** to run a live check straight away.

{% hint style="info" %}
Herd connects **one Confluence site per organization**. If your authorization covers several sites, Herd uses the first one that has Confluence access. To switch sites later, click **Reconnect** and choose a different site on the consent screen.
{% endhint %}

## Part 3: Link policies to Confluence pages

### Step 1: Copy the page URL

Open the page in Confluence and copy the address from your browser's address bar. It looks like one of these:

* `https://your-site.atlassian.net/wiki/spaces/SEC/pages/123456789/Acceptable-Use-Policy`
* `https://your-site.atlassian.net/wiki/spaces/SEC/blog/2026/01/15/123456789/Post-Title` (blog posts)
* `https://your-site.atlassian.net/wiki/pages/viewpage.action?pageId=123456789` (older links)

{% hint style="warning" %}
Do not use a **short link** from Confluence's share dialog (`https://your-site.atlassian.net/wiki/x/AbCdEf` or `/l/cp/AbCdEf12`). Herd recognises these as Confluence links but cannot read the page behind them, so the policy would be saved with no content. Open the page and copy the full URL from the address bar instead.
{% endhint %}

The page must be on the site you connected. A link to a page on a different Atlassian site is saved, but its content is not indexed.

### Step 2: Create the policy

1. On the **Policies** page, click **Create Policy**.
2. Choose **External Link** and paste the page URL.
3. Uncheck **Auto-fill from document** and expand **Policy Details** to enter the policy name, type, and message yourself. Auto-fill can only see the link itself, not the page body, so the suggestions it makes for a Confluence link are not based on your content.
4. Continue through the remaining steps as for any other policy (see [Creating a Policy](/herd-security-docs/policies/policies.md#creating-a-policy)) and click **Create Policy**.

You can also link an existing policy to a Confluence page by editing it and switching its document to **External Link**.

### What happens next

* Herd reads the page as soon as the policy is saved and adds its content to the knowledge index that grounds Herd AI. Members can ask the Herd bot questions like *"what does our policy say about USB drives?"* and get answers from the live page.
* Herd re-reads every linked page **once a day**, so edits you make in Confluence show up in Herd AI's answers within a day. There is nothing to re-upload.
* On the policy's **Details** tab, the document link carries a **Confluence** label.
* When you assign the policy, the **View policy document** link in Slack, Teams, or the email opens the page in Confluence. Recipients need access to the page in Confluence to read it there.

## Maintaining the connection

The Confluence tile offers four actions once connected:

* **Check connection** runs a live request against your site and records the result and time on the tile.
* **Reconnect** re-runs the Atlassian authorization with the saved app. Use it after a failed check, or to switch to a different site.
* **Re-enter credentials** replaces the client ID and secret, for example after rotating the secret in the Atlassian developer console. Saving new credentials clears the authorization, so click **Connect to Confluence** again afterwards.
* **Disconnect** stops Herd from reading Confluence. Policies you have already linked keep their links but stop updating, and Herd AI no longer searches your site.

If a check fails, the tile marks the site as **needs reconnect** and shows the error.

### Letting another account authorize the app

Atlassian keeps a new OAuth app private, so only its creator can authorize it. If someone other than the app's creator needs to click **Connect to Confluence** or **Reconnect**, open the app in the Atlassian developer console, click **Distribution** in the left menu, and turn on sharing. Fill in the vendor details Atlassian asks for; the app stays unlisted and is not published to the Atlassian Marketplace.

## Troubleshooting

| What you see                                                                                                        | What it means                                                                                        | What to do                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Atlassian shows an error about the redirect URI after you click **Connect to Confluence**                           | The callback URL in the Atlassian app does not exactly match the one on the Herd tile                | Re-copy the **Callback URL** from the tile into the app's **Authorization** settings and save                        |
| "No Confluence site was granted to this app" after authorizing                                                      | You accepted on a site without Confluence, or the app has no Confluence API permissions              | Check **Permissions** in the Atlassian app, then **Reconnect** and pick a site that has Confluence                   |
| The tile says "Could not refresh Confluence access — the authorization was revoked or expired. Reconnect the site." | The grant was revoked in Atlassian, or the app's secret changed                                      | Click **Reconnect**. If the secret was rotated, click **Re-enter credentials** first                                 |
| Only the app's creator can authorize; other admins get an Atlassian error                                           | The app is still private                                                                             | See [Letting another account authorize the app](#letting-another-account-authorize-the-app)                          |
| A linked policy has no content in Herd AI answers                                                                   | The link is a short link, points to a different site, or the authorizing account cannot see the page | Re-link using the full page URL from the address bar, and confirm the account that authorized Herd can open the page |

## Herd AI and Confluence

Beyond the policies you link, admins with the org-integrations permission can ask HerdAI to search or read any page on the connected site, for example *"find our incident response runbook in Confluence"*. Everyone else gets answers only from the pages you have linked as policies. Both use the same read-only connection.