Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 in the Atlassian developer console.

  2. Connect the app in Herd.

  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 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.

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.

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:

Step 2: Create the app

  1. Open the Atlassian developer console 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.

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.

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.

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.

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)

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.

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) 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

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.

PreviousPolicies
NextAnnouncements

Last updated