---
title: Connect Confluence
canonical: "https://agentbarn.dev/guides/integrations/confluence"
pubDate: "2026-08-29T00:00:00.000Z"
updatedDate: "2026-09-13T13:41:42.000Z"
author: Agent Barn
description: "Connect Confluence Cloud to an Agent Barn Agent with a scoped or non-scoped Atlassian API token, resolved Cloud ID, space-level permissions, and validation."
tags: [Integrations, How-to, "Confluence administrators, Agent operators, and Organization administrators", Confluence, Atlassian, Confluence API token, scoped token, Cloud ID, confluence-work profile, space permissions, page restrictions, shared credential]
categories: [Guides, Integrations]
---

-   Integrations
-   10–15 minutes
-   Requires an Atlassian API token

Connect Confluence to let an Agent search spaces, read pages, work with comments, and, when permitted, create or update pages and attachments.

Agent Barn stores the Atlassian API token as an encrypted Agent Secret, and creates an `aai-cli` profile named `confluence-work` when the Agent starts.

**Authorization boundary**

The Atlassian account’s Confluence product access, space permissions, and page restrictions determine what the Agent can see and change. The site URL alone is not an access restriction.

## Connection model

1.  Atlassian account
2.  API token
3.  Encrypted Agent Secret
4.  confluence-work profile
5.  Confluence Cloud

The credential authenticates the Agent. The Confluence Skill supplies the `aai-cli` workflows the Agent runs against it.

## Before you begin

You need:

-   A Confluence Cloud site
-   An Atlassian account with Confluence product access
-   Permission to create an Atlassian API token
-   The base Confluence site URL
-   The email address associated with the token
-   Access to configure the Agent
-   `agent.update` and `agent.secret.manage` permissions
-   Lifecycle permission when connecting a running Agent

Decide whether the Agent needs read-only space and page access, page creation or editing, page comments, attachment downloads, or attachment uploads.

Use a dedicated Atlassian account or service identity when possible.

## Understand the credential fields

| Field | Purpose |
| --- | --- |
| Site URL | Identifies the Atlassian Cloud tenant |
| Authentication type | Selects scoped or non-scoped token routing |
| Email | Atlassian account associated with the token |
| API token | Authenticates the account |
| Cloud ID | Resolved and stored internally for scoped tokens |

Use the base Atlassian site URL:

```
https://example.atlassian.net
```

Do not enter a wiki route or REST path:

```
https://example.atlassian.net/wiki

https://example.atlassian.net/wiki/rest/api
```

Agent Barn adds the Confluence API paths.

## Choose an authentication type

Agent Barn supports scoped and non-scoped Atlassian API tokens. Both use Basic authentication with the account email and token.

### Non-scoped token

A standard Atlassian account API token, accessing Confluence through the site.

```
https://example.atlassian.net/wiki/...
```

Choose this for standard direct-site API access.

### Scoped token

Accesses Confluence through Atlassian’s API Gateway using the resolved Cloud ID.

```
https://api.atlassian.com/ex/confluence/{cloud_id}/wiki/...
```

Choose this when the token must use Atlassian’s API Gateway.

**Important**

Agent Barn resolves the Cloud ID automatically. Do not add it to the site URL or the credential form.

## How Cloud ID resolution works

For scoped credentials, Agent Barn requests tenant metadata from the site and uses the returned Cloud ID to build the runtime API gateway URL.

1.  **Confluence site** The base Atlassian site URL saved with the credential
    
2.  **/\_edge/tenant\_info** Agent Barn requests the site’s tenant metadata
    
3.  **Cloud ID** Stored with the encrypted credential
    
4.  **api.atlassian.com/ex/confluence/{cloud\_id}** The gateway host used by scoped tokens at runtime
    

**Scoped token**

Validate every scoped Confluence credential. If Cloud ID discovery fails, Agent Barn cannot generate a usable `confluence-work` profile.

## Plan Confluence permissions

Grant only the permissions required by the Agent’s workflow.

| Agent workflow | Common Confluence requirement |
| --- | --- |
| List spaces | Confluence product access and visibility of the space |
| Read pages | View permission for the space and page |
| Read comments | View access to the page |
| Add comments | Add Comments permission |
| Create pages | Add Pages permission in the space |
| Update pages | Permission to edit the page |
| List or download attachments | View access to the page and attachment |
| Upload attachments | Add Attachments permission |
| Delete content | Corresponding delete permission |

Page-level restrictions can further reduce access inside an otherwise visible space. Start with view access, and add write permissions only for documented workflows.

**Important**

Agent Barn validates the credential against Confluence, but it does not inspect every space permission or page restriction.

## Create the API token

Using the intended Atlassian account:

1.  Open the account’s security settings.
2.  Go to API token management.
3.  Create the appropriate scoped or non-scoped token.
4.  Give it a descriptive name, such as `Agent Barn: Knowledge Agent`.
5.  Set an expiration or rotation plan when available.
6.  Copy the token.
7.  Record which authentication type it uses.

**Security**

Do not use the Atlassian account password. Treat the API token as a secret, and never paste it into a Template, Skill, prompt, or Agent conversation.

## Prepare the Confluence account

Before connecting:

1.  Confirm that the account can access the Confluence site.
2.  Confirm that it has Confluence product access.
3.  Open each intended space.
4.  Verify page visibility.
5.  Review space permissions.
6.  Review page-level restrictions.
7.  Remove access to unrelated spaces where possible.
8.  Test one read-only action using the account.

The API token inherits the account’s effective Confluence access.

## Connect Confluence in Agent Barn

1.  Stop the Agent, or begin the web interface’s restart-aware edit flow.
2.  Open the Agent.
3.  Go to **Configuration**.
4.  Select **Keys & integrations**.
5.  Select **Edit**.
6.  Add **Confluence** under Integration credentials.
7.  Choose **Enter credentials**.
8.  Enter the base Atlassian site URL.
9.  Select **Scoped token** or **Non-scoped token**.
10.  Enter the account email.
11.  Paste the API token.
12.  Apply the configuration.
13.  Restart the Agent if it was running.
14.  Validate the credential.
15.  Test space and page access.

The token is hidden after it is saved.

### Use a Shared Confluence Credential

Confluence is supported by Organization Shared Credentials. To attach one:

1.  Open the Agent’s integration configuration.
2.  Select Confluence.
3.  Choose **Use shared credential**.
4.  Select the named Confluence credential.
5.  Apply the configuration.
6.  Restart the Agent.
7.  Validate and test the connection.

**Shared credential**

An Agent can use either a manual Confluence credential or a Shared Confluence Credential, not both. See [Use shared credentials](/guides/integrations/shared-credentials) for the complete lifecycle.

### Assign the Confluence Skill

The credential supplies authentication. The Confluence Skill gives the Agent detailed `aai-cli` instructions.

If the active Template requires Confluence:

1.  Open the Agent’s **Skills** configuration.
2.  Confirm that the Confluence Skill is assigned.
3.  Confirm its pinned version.
4.  Save the configuration.
5.  Start the Agent.

An explicit Template requirement must be satisfied by an explicit Skill assignment.

## Validate the credential

1.  Open **Keys & integrations**.
2.  Find **Confluence**.
3.  Select **Validate**.
4.  Review the returned identity or service-account summary.
5.  Resolve authentication errors.
6.  Continue with space-level testing.

### Validate a non-scoped credential

For a non-scoped token, Agent Barn requests:

```
https://example.atlassian.net/wiki/rest/api/user/current
```

Validation confirms that the site is reachable, the email and token authenticate, the account has Confluence product access, authentication was not treated as anonymous, and the connected identity is available.

```
{
  "validation_status": "valid",
  "validation_identity": "Knowledge Agent (agent@example.com)",
  "validation_error": null,
  "missing_scopes": []
}
```

### Validate a scoped credential

Scoped tokens cannot use the legacy current-user endpoint used for non-scoped identity validation. Agent Barn instead requests:

```
https://api.atlassian.com/ex/confluence/{cloud_id}/wiki/api/v2/spaces
```

Any successful response confirms that the scoped token can authenticate through the gateway. The identity is reported as a service-account-style site summary:

```
Service account (example.atlassian.net) · 3 space(s) accessible
```

The count reflects the first returned result set, and should be treated as a connectivity summary rather than a complete access audit.

**Important**

A successful validation does not prove access to every intended space or page. Continue with space-level and page-level testing.

## Verify access

**Verification**

Verify spaces before pages, and reads before writes. Use a designated test space for anything that creates or changes content.

### Verify space access

```
List the Confluence spaces available to the connected account.
```

```
aai-cli confluence spaces list \
  --limit 20 \
  --profile confluence-work
```

To check a known space:

```
aai-cli confluence spaces get DOCS \
  --profile confluence-work
```

Review the results for missing intended spaces and unexpected access.

### Verify page listing and reads

```
aai-cli confluence pages list \
  --space DOCS \
  --status current \
  --limit 10 \
  --profile confluence-work
```

Using a specific space key reduces the chance of exposing unrelated content during verification.

Read a known non-sensitive page:

```
aai-cli confluence pages get 3964929 \
  --profile confluence-work
```

Confluence page operations use numeric page IDs. Confirm that the Agent can see the expected body and metadata without accessing restricted pages.

### Verify comments

```
aai-cli confluence pages comments list 3964929 \
  --limit 10 \
  --profile confluence-work
```

To test comment creation on a designated page:

```
aai-cli confluence pages comments create 3964929 \
  --body "Agent Barn integration verification." \
  --profile confluence-work
```

Do not test writes against production documentation without approval.

### Verify attachments

```
aai-cli confluence pages attachments list 3964929 \
  --limit 10 \
  --profile confluence-work
```

Download a known non-sensitive attachment:

```
aai-cli confluence pages attachments download \
  3964929 \
  att3997705 \
  --output local/logs/confluence-verification.txt \
  --profile confluence-work
```

Attachment upload requires separate write permission, and should be tested only on a designated page.

### Verify page creation or editing

For an Agent intended to write pages, use a test space.

```
aai-cli confluence pages create \
  --space-key DOCS \
  --title "Agent Barn integration verification" \
  --body "Temporary verification page." \
  --profile confluence-work
```

```
aai-cli confluence pages update 3964929 \
  --title "Agent Barn integration verification: updated" \
  --body "Updated verification content." \
  --profile confluence-work
```

Clean up temporary content after the test.

## Runtime behavior

When the Agent starts, Agent Barn:

1.  Decrypts the Confluence credential.
2.  Resolves the Cloud ID for scoped tokens when needed.
3.  Stores the API token in the runtime secret store.
4.  Creates the `confluence-work` profile.
5.  Mounts eligible Confluence Skill instructions.
6.  Adds the site URL and account email to the integration context.

For a non-scoped token:

```
[profiles.confluence-work]
auth_type = "basic_api_token"
site_url = "https://example.atlassian.net"
email = "agent@example.com"
api_token_secret = "confluence.api_token"
```

For a scoped token, the profile uses the Atlassian gateway host with the resolved Cloud ID.

**Runtime**

Every `aai-cli confluence` command requires `--profile confluence-work`. The Agent should never ask users to paste a token into conversation.

### Scoped-token save behavior

When a scoped credential is saved, Agent Barn attempts to resolve and store its Cloud ID. If discovery temporarily fails, the credential may be saved without a Cloud ID, and runtime profile generation then skips the Confluence profile.

If validation reports a Cloud ID error:

1.  Confirm the base site URL.
2.  Confirm that the site is reachable from Agent Barn.
3.  Save the complete credential again.
4.  Validate it.
5.  Restart the Agent.

## Rotate the token

1.  Create a replacement token in Atlassian.
2.  Record whether it is scoped or non-scoped.
3.  Stop the Agent, or begin a restart-aware edit.
4.  Open **Keys & integrations**.
5.  Enter the complete replacement Confluence credential.
6.  Re-enter the site URL, authentication type, and email.
7.  Apply and restart.
8.  Validate the credential.
9.  Test space and page access.
10.  Revoke the old token.

Stored credential values cannot be retrieved or partially edited.

### Change the Confluence account

1.  Prepare a token for the replacement Atlassian account.
2.  Confirm its product, space, and page access.
3.  Replace the complete credential.
4.  Apply and restart.
5.  Validate the identity.
6.  Test intended spaces and pages.
7.  Revoke the old token when appropriate.

The replacement account may have different page restrictions, even when it belongs to the same spaces.

## Remove Confluence access

1.  Stop the Agent, or begin a restart-aware edit.
2.  Identify any assigned Skill requiring `confluence`.
3.  Remove or replace the Skill when permitted.
4.  Open **Keys & integrations**.
5.  Select **Remove** for Confluence.
6.  Apply the configuration.
7.  Restart the Agent.
8.  Confirm that Confluence is unavailable.
9.  Revoke the token in Atlassian.

Agent Barn rejects removal while a remaining assigned Skill requires Confluence.

## API reference

### Add a non-scoped Confluence credential

The Agent must be stopped.

```
PATCH /api/v1/organizations/{organization_id}/agents/{agent_id}
Content-Type: application/json
```

```
{
  "secrets": [
    {
      "provider": "confluence",
      "content": {
        "site_url": "https://example.atlassian.net",
        "use_scoped_token": false,
        "email": "agent@example.com",
        "api_token": "REDACTED"
      }
    }
  ]
}
```

### Add a scoped Confluence credential

```
{
  "secrets": [
    {
      "provider": "confluence",
      "content": {
        "site_url": "https://example.atlassian.net",
        "use_scoped_token": true,
        "email": "agent@example.com",
        "api_token": "REDACTED"
      }
    }
  ]
}
```

Do not submit `cloud_id`. Agent Barn resolves it internally. Every token value in these examples is redacted; supply your own.

### Attach a Shared Confluence Credential

```
{
  "shared_credentials": [
    {
      "shared_credential_id": "3fd08cf5-59c5-494b-9449-a0413109a0ca"
    }
  ]
}
```

### Validate Confluence

```
POST /api/v1/organizations/{organization_id}/agents/{agent_id}/integrations/confluence/validate
```

Validation requires `agent.secret.manage`.

### Remove Confluence

```
{
  "removed_secret_providers": [
    "confluence"
  ]
}
```

## Troubleshooting

### Validation says “Invalid email or API token”

Check the pair and the token type

Check that:

-   The email belongs to the token’s Atlassian account
-   The token was copied completely
-   The correct authentication type is selected
-   The token has not expired or been revoked
-   The site URL identifies the correct Atlassian tenant

### Validation says the account has no Confluence product access

Product access is separate

Grant Confluence product access to the account, or connect another account.

### Validation says authentication was not accepted

The request was treated as anonymous

The non-scoped endpoint treated the request as anonymous.

Check the email, token, authentication type, and site URL.

### Agent Barn cannot resolve the Cloud ID

Use the base site URL

Use the base site URL:

```
https://example.atlassian.net
```

Do not include `/wiki` or a REST API path. Save and validate the scoped credential again.

### Runtime logs say cloud\_id missing

Saved before discovery succeeded

Re-enter and save the complete scoped credential, validate it, and restart the Agent.

### Validation succeeds, but an intended space is missing

Space visibility is separate

The account likely lacks space visibility or product access to that space.

Review the space permissions and account membership.

### A space is visible, but a page returns 404 or 403

Page restrictions override visibility

Page restrictions can override general space visibility.

Grant the account access to that page or its restricted ancestor only when appropriate.

### Pages can be read, but comments fail

Add Comments is separate

The account may lack Add Comments permission in that space.

### Pages can be read, but creation or updates fail

Add Pages and edit restrictions

Review Add Pages permission, page edit restrictions, and the parent page’s restrictions.

### Attachment listing works, but upload fails

Add Attachments is separate

The account may lack Add Attachments permission.

### Scoped validation shows fewer spaces than expected

The count is a connectivity summary

The displayed count is a summary of the returned v2 result page, not a full permission audit.

Run `spaces list` through the Agent and test each intended space.

### A Shared Credential conflicts with a manual Confluence token

One source per provider

An Agent can use only one Confluence credential source.

Remove the manual credential before attaching the Shared Credential, or replace the Shared attachment with a manual credential.

### Confluence was connected but the Agent cannot use it

Restart, Skill, profile, or permissions

Check that:

-   The Agent restarted after saving
-   The Confluence Skill is assigned when required
-   The expected Skill version is pinned
-   The `confluence-work` profile was generated
-   Validation succeeds
-   The account can access the intended spaces and pages
-   Startup logs do not report a missing Cloud ID

## Recommended practices

-   Use a dedicated Atlassian identity for production Agents
-   Restrict the account to intended spaces
-   Review page-level restrictions
-   Begin with view-only access
-   Add comment, page, and attachment permissions separately
-   Use different credentials for Agents with different knowledge boundaries
-   Select the correct scoped-token setting
-   Validate every scoped credential
-   Test space access before page access
-   Test reads before writes
-   Use a designated test space for verification
-   Rotate tokens on a documented schedule
-   Revoke old and unused tokens
-   Never place Confluence tokens in Templates, Skills, prompts, or conversations
-   Review space permissions when an Agent’s responsibilities change

## Next steps

Continue to [Connect Bitbucket](/guides/integrations/bitbucket) to configure repository access with an appropriately scoped Bitbucket token.

-   [Connect Jira](/guides/integrations/jira)
-   [Manage Agent credentials](/guides/integrations/credentials)
-   [Use shared credentials](/guides/integrations/shared-credentials)