Skip to main content

Confluence

Confluence is a team workspace and knowledge management tool for creating, organizing, and collaborating on documentation, meeting notes, project plans, and more.

This connector targets Confluence Cloud. For the self-hosted product, use Confluence Data Center instead. If you want Jira and Confluence together behind one server, see the official Atlassian MCP server.

Authentication Types​

  • OAuth - Register your own OAuth 2.0 (3LO) app in the Atlassian developer console.
    • Pros: your own consent screen, your own scope set, your own audit trail
    • Cons: needs an Atlassian admin and a few minutes of setup
  • API Key - Authenticate with one shared credential: either a classic API token from a dedicated account (a "technical user") or a scoped token from an Atlassian service account.
    • Pros: no app registration, no consent screen, quickest way to a working connection
    • Cons: one shared credential for everyone, so there is no per-user audit trail; every request runs with that identity's permissions.
  • API Key Per User - Each user supplies their own Atlassian email and API token.
    • Pros: per-user permissions and audit trail without registering an OAuth app
    • Cons: every user must create and paste their own token

The OAuth and API Key Per User options authorize per user, so each person sees only the spaces and pages their own Confluence account can reach. The shared API Key option runs every request as the single configured account. See Configure authentication for where these live on the Setup tab.

Configuration​

  • Confluence Organization Domain - The base URL Willow calls. You set this yourself to match how you authenticate:
    • OAuth and API Key with a service-account token: the Atlassian API gateway, https://api.atlassian.com/ex/confluence/{cloudId}. Atlassian only accepts 3LO and scoped tokens through this gateway. Find {cloudId} by opening https://your-org.atlassian.net/_edge/tenant_info in your browser and copying the cloudId value from the JSON response.
    • API Key with a classic token (email:api_token) and API Key Per User: your bare site, https://your-org.atlassian.net.
Authentication typeCredentialOrganization Domain to enterAuth header Willow sends
OAuth3LO access tokenhttps://api.atlassian.com/ex/confluence/{cloudId}Bearer <token>
API Key (classic token)email:api_tokenhttps://your-org.atlassian.netBasic base64(email:token)
API Key (service account)scoped token (no email)https://api.atlassian.com/ex/confluence/{cloudId}Bearer <token>
API Key Per Useremail:api_tokenhttps://your-org.atlassian.netBasic base64(email:token)

Willow chooses the header from the credential format: a value containing a colon (email:api_token) is sent as Basic, and a bare token (a scoped service-account token) is sent as Bearer. Set the Organization Domain to match — 3LO and scoped tokens only work against the gateway, classic tokens only against the bare site.

On OAuth you can skip the Cloud ID lookup and just enter your site, https://your-org.atlassian.net. When you save, Willow reads the Cloud ID from the site and stores the gateway URL instead, then shows you what it saved. The API Key types are left exactly as you enter them, so a service-account token still needs the gateway URL typed out in full.

Setting up OAuth​

Use this path when the integration should run under your organization's own Atlassian app.

Create the app in Atlassian​

  1. Go to the Atlassian developer console and sign in with an account that can create apps for your site.
  2. Create a new app and enable OAuth 2.0 (3LO).
  3. Add the Confluence API to the app.
  4. Set the Callback URL to the redirect URL Willow shows on the connector's Setup tab. Copy it from Willow rather than typing it; Atlassian rejects the authorization if it does not match exactly.
  5. Under Permissions, add the granular Confluence scopes your tool selection needs. See the table below.
  6. Copy the Client ID and Secret from the app's Settings page.

Configure it in Willow​

  1. In Willow, open Build > MCP Servers > Add MCP Server, search for Confluence, and select Use.
  2. Review the risk level and tool list, then select Create.
  3. On the server's Setup tab, choose OAuth.
  4. Paste the Client ID and Client Secret, add the same scopes you granted in Atlassian, and select Save Changes.
  5. Set the Confluence Organization Domain to the Atlassian API gateway base, https://api.atlassian.com/ex/confluence/{cloudId} (see Configuration for how to find your Cloud ID). OAuth (3LO) tokens are only accepted through this gateway.

Setting up API Key​

Use this path to authenticate with an Atlassian API token instead of registering an OAuth app. Choose API Key for one shared credential, or API Key Per User so each person authenticates as themselves.

The shared API Key option accepts either kind of Atlassian token:

  • Classic token from a technical user — a dedicated regular (licensed) Atlassian account. The credential is email:api_token, sent as Basic against your bare site.
  • Scoped token from a service account — a license-free Atlassian identity created by an org admin. The credential is the bare token (no email), sent as Bearer against the API gateway.

Create a classic token (technical user)​

  1. Sign in to the dedicated Atlassian account you want the integration to act as (a "technical user"), not a personal login.
  2. Go to id.atlassian.com/manage-profile/security/api-tokens.
  3. Click Create API token (a classic, unscoped token — not "Create API token with scopes"), give it a label, and optionally set an expiry date.
  4. Click Create and copy the token immediately — Atlassian won't show it again.

Create a scoped token (service account)​

  1. As an Atlassian org admin, create or open a service account and create an API token with the Confluence scopes your enabled tools need (see Scopes each tool group needs).
  2. Copy the token immediately — Atlassian won't show it again.

Configure it in Willow​

  1. In Willow, open Build > MCP Servers > Add MCP Server, search for Confluence, and select Use.
  2. Review the risk level and tool list, then select Create.
  3. On the server's Setup tab, choose API Key (one shared credential) or API Key Per User (each user pastes their own).
  4. Enter the credential:
    • Classic token: email:api_token — your Atlassian account email, a colon, then the token (for example you@example.com:your_api_token).
    • Scoped service-account token: paste the token on its own, with no email and no colon.
  5. Set the Confluence Organization Domain to match your credential (see the Configuration table): the bare site https://your-org.atlassian.net for a classic token, or the gateway https://api.atlassian.com/ex/confluence/{cloudId} for a scoped service-account token.
  6. Select Save Changes.

A classic API token inherits the Confluence permissions of the account that created it, so scopes do not apply — the connector can do whatever that account can do in Confluence. A scoped service-account token is limited to the scopes granted on the token. The scope table below applies to OAuth and to scoped service-account tokens.

Service accounts​

Atlassian's service accounts (non-human identities that don't consume a license, created by an org admin with Atlassian Guard) are supported through the API Key flow.

A service account can only create scoped API tokens, which Atlassian accepts as Authorization: Bearer <token> against the https://api.atlassian.com/ex/confluence/{cloudId} gateway. Because a scoped token has no email: prefix, Willow detects it from the credential format and sends it as Bearer automatically — you just set the Confluence Organization Domain to the gateway base (see Configuration).

If you prefer a classic email:api_token credential instead, create a dedicated regular user (a "technical user") and use its classic token against the bare site. That account consumes a Confluence license; a service account does not.

Scopes each tool group needs​

Atlassian's granular scopes map onto the connector's tools. Grant only what your enabled tools require.

ToolsConfluence scope
Search Content, Get Page, List Pages in Space, Get Child Pagesread:page:confluence
List Spaces, Get Spaceread:space-details:confluence
Get Comments, Get Labels, Get Attachments, Download Attachmentread:content:confluence and read:content-details:confluence
Create Page, Update Page, Create Blog Post, Add Comment, Add Labels, Upload Attachmentwrite:page:confluence, write:blogpost:confluence, and write:content:confluence
Delete Pagedelete:page:confluence

Atlassian maintains the authoritative list, including scopes for whiteboards, databases, and folders that this connector does not use. See Confluence scopes for OAuth 2.0 (3LO).

Available Tools​

The connector exposes 17 tools. At the default Medium Risk level Willow enables 16 and holds back Delete Page.

Read-only​

Search Content, Get Page, List Pages in Space, List Spaces, Get Space, Get Child Pages, Get Comments, Get Labels, Get Attachments, Download Attachment

Create and update​

Create Page, Update Page, Create Blog Post, Add Comment, Add Labels, Upload Attachment

Delete​

Delete Page, classified high risk and excluded at Medium.

Troubleshooting​

The authorization redirect fails. The callback URL in the Atlassian app does not match the one on Willow's Setup tab. Copy it again from Willow, including the scheme and any trailing path.

A tool returns a permission error but the user can do it in Confluence. On OAuth, the app is missing the scope for that operation — add it in the developer console, then have the user disconnect and reconnect; existing authorizations do not pick up new scopes. On API Key, the token's account lacks the Confluence permission — check that account's space permissions in Confluence.

API token auth returns 401 Unauthorized. The credential format and the Organization Domain must match. For a classic token, use the email:api_token format (email, colon, token) and set the domain to the bare site (https://your-org.atlassian.net). For a scoped service-account token, paste the token alone (no email, no colon) and set the domain to the gateway (https://api.atlassian.com/ex/confluence/{cloudId}). A classic token sent to the gateway, or a scoped token sent to the bare site, returns 401. Also confirm the token hasn't expired.

Pages are missing from results. Authorization is per user, so the connector returns only what that person can already see. Check their Confluence space permissions before checking Willow.

On this page