Confluence (user passthrough)

Proxy for the Atlassian Confluence Cloud REST API via the managed gateway.

What this connector does

Gives agents gated, per-user access to Confluence for:

• Searching content with CQL.
• Reading pages (with body), their children, labels, and attachments.
• Listing spaces and the pages within them.
• Reading and posting page (footer) comments.
• Creating and updating pages.

All operations are gated by PBAC policy. Every call flows: agent → gateway → /introspect (with this connector's resource_type) → OPA decision → Confluence API → response.

This connector ships in idp_passthrough mode only: the gateway forwards each calling user's own Atlassian OAuth token (captured when they log in to PolicyArc through the Atlassian IdP), as Authorization: Bearer. Confluence enforces its own space and page permissions, and its audit shows the real person. There is no shared service-account mode — Atlassian Cloud exposes no service identity at the OAuth layer (see the Atlassian products page).

API surface

Content and spaces use the Confluence v2 API (/wiki/api/v2/*), Atlassian's current REST API. CQL search uses the v1 endpoint (/wiki/rest/api/search) because v2 has no CQL equivalent.

Because the v2 API is used, the connector requests granular Atlassian OAuth scopes (read:page:confluence, write:page:confluence, read:space:confluence, read:comment:confluence, write:comment:confluence, read:attachment:confluence, read:label:confluence, search:confluence, plus read:me and offline_access) — not the classic read:confluence-content.all family, which the v2 API rejects with HTTP 401 "scope does not match". Grant these granular scopes on the Atlassian 3LO app's Confluence API permission.

Two Confluence quirks the tools document inline:

• Body representation. Page and comment bodies use the storage representation (Confluence XHTML), e.g. {"representation": "storage", "value": "<p>Hello</p>"} — not plain text.
• Optimistic locking on update. update_page requires the next version number. Call get_page first, read version.number, then pass version: {"number": N+1}.

Prerequisites

• A Confluence Cloud account with access to the spaces/pages you want to reach.
• An Atlassian IdP registered in PolicyArc (provider key atlassian). Pick Atlassian in the IdP setup wizard — the bundled preset fills in the endpoints and the required audience=api.atlassian.com authorize param. You supply the Client ID / secret from an Atlassian OAuth 2.0 (3LO) app (developer.atlassian.com) whose callback URL is the AS's /oauth2/callback, with the Confluence API permission granted for the connector's granular scopes (see above).
• Your site's cloud ID — get it from https://<site>.atlassian.net/_edge/tenant_info.

See Atlassian products — multi-connector setup for the full 3LO walkthrough (shared with the Jira connector).

Install

Provide two setup fields: Atlassian site (the subdomain, e.g. acme) and Atlassian cloud ID (the UUID). Passthrough installs need no secret. On install, the gateway merges this connector's upstream_scopes into the Atlassian IdP row, so users re-consent to the union on their next login.

Verify

Request a token with a Confluence scope and call through the gateway as a logged-in user (passthrough needs a user session, so client_credentials will return a 502 "no stored IdP token"):

curl "https://<your-as>/gateway/confluence/wiki/api/v2/spaces" \
  -H "Authorization: Bearer <user-token>"

A 200 with the spaces JSON confirms: token → introspect allowed → gateway proxied → Confluence responded as the user.

What can go wrong

Symptom	Cause	Fix
502 "no stored IdP token"	Caller never logged in through the atlassian IdP (or used client_credentials, which has no user context)	Re-authenticate via Atlassian.
403 from Confluence	The user lacks permission on the space/page, or the token is missing a scope	Check the user's Confluence permissions and that the Atlassian app granted the scope.
400 on create/update	Body sent as plain text instead of the storage representation	Wrap content as {"representation": "storage", "value": "<p>...</p>"}.
409 on update	Stale version.number	Re-read with get_page and pass version.number + 1.
403 from the gateway	Agent lacks the route's PBAC scope	Request a token with the matching confluence:* scope.
Stored IdP token missing required scopes	Connector installed after the user logged in	User signs out and back in to re-consent.

Reference

• Manifest: connectors/identos.confluence/connector.v1.json in the repo.
• IdP preset: src/main/resources/idp-presets/atlassian.json.
• Multi-connector setup: Atlassian products.
• Upstream API docs: Confluence Cloud v2 REST API.

Manifest reference

• ID: identos.confluence
• Version: 1.1.0
• Resource type: urn:connector:identos:confluence
• Capabilities: mcp

Supported auth modes

Type	Details
idp_passthrough	requires IdP atlassian; setup fields: site, cloudid

Setup fields

ID	Label	Default	Secret?	Notes
site	Atlassian site	—	no	placeholder: acme / The subdomain of your Atlassian cloud URL (e.g. 'acme' for acme.atlassian.net). Used in resource IDs and to locate the cloud ID.
cloudid	Atlassian cloud ID	—	no	placeholder: 11223344-5566-7788-9900-aabbccddeeff / UUID identifying your Atlassian site. Get from https://{site}.atlassian.net/_edge/tenant_info (the cloudId field). Required because Atlassian Cloud OAuth tokens route through https://api.atlassian.com/ex/confluence/\{cloudid\}/, not the site URL directly.

Scopes

Scope
confluence:content:read
confluence:content:write
confluence:content:delete
confluence:space:read
confluence:comments:read
confluence:comments:write

Routes

Method	Pattern	Scope	Resource template
GET	/wiki/rest/api/search	confluence:content:read	—
GET	/wiki/api/v2/pages/{id}	confluence:content:read	confluence://{{site}}/pages/{{id}}
GET	/wiki/api/v2/pages	confluence:content:read	—
GET	/wiki/api/v2/pages/{id}/children	confluence:content:read	confluence://{{site}}/pages/{{id}}
GET	/wiki/api/v2/pages/{id}/labels	confluence:content:read	confluence://{{site}}/pages/{{id}}
POST	/wiki/rest/api/content/{id}/label	confluence:content:write	confluence://{{site}}/pages/{{id}}
DELETE	/wiki/rest/api/content/{id}/label	confluence:content:write	confluence://{{site}}/pages/{{id}}
GET	/wiki/api/v2/pages/{id}/attachments	confluence:content:read	confluence://{{site}}/pages/{{id}}
GET	/wiki/api/v2/attachments/{id}	confluence:content:read	confluence://{{site}}/attachments/{{id}}
GET	/wiki/api/v2/spaces	confluence:space:read	—
GET	/wiki/api/v2/spaces/{id}	confluence:space:read	confluence://{{site}}/spaces/{{id}}
GET	/wiki/api/v2/spaces/{id}/pages	confluence:space:read	confluence://{{site}}/spaces/{{id}}
GET	/wiki/api/v2/pages/{id}/footer-comments	confluence:comments:read	confluence://{{site}}/pages/{{id}}
GET	/wiki/api/v2/pages/{id}/inline-comments	confluence:comments:read	confluence://{{site}}/pages/{{id}}
GET	/wiki/api/v2/footer-comments/{id}	confluence:comments:read	confluence://{{site}}/comments/{{id}}
GET	/wiki/api/v2/pages/{id}/versions	confluence:content:read	confluence://{{site}}/pages/{{id}}
GET	/wiki/api/v2/folders/{id}	confluence:content:read	confluence://{{site}}/folders/{{id}}
GET	/wiki/api/v2/blogposts	confluence:content:read	—
GET	/wiki/api/v2/blogposts/{id}	confluence:content:read	confluence://{{site}}/blogposts/{{id}}
POST	/wiki/api/v2/pages	confluence:content:write	—
POST	/wiki/api/v2/blogposts	confluence:content:write	—
POST	/wiki/api/v2/folders	confluence:content:write	—
PUT	/wiki/api/v2/pages/{id}	confluence:content:write	confluence://{{site}}/pages/{{id}}
PUT	/wiki/rest/api/content/{id}/move/{position}/{targetId}	confluence:content:write	confluence://{{site}}/pages/{{id}}
PUT	/wiki/api/v2/footer-comments/{id}	confluence:comments:write	confluence://{{site}}/comments/{{id}}
POST	/wiki/api/v2/footer-comments	confluence:comments:write	—
POST	/wiki/api/v2/inline-comments	confluence:comments:write	—
DELETE	/wiki/api/v2/pages/{id}	confluence:content:delete	confluence://{{site}}/pages/{{id}}
DELETE	/wiki/api/v2/folders/{id}	confluence:content:delete	confluence://{{site}}/folders/{{id}}
DELETE	/wiki/api/v2/footer-comments/{id}	confluence:comments:write	confluence://{{site}}/comments/{{id}}

MCP tools

Name	Scope	Description
search_pages	confluence:content:read	Search Confluence content with CQL (Confluence Query Language). Example cql: "type=page AND space=DEV AND text ~ "onboarding"". Returns {results, _links:{next}, ...}; pass the opaque cursor from _links.next (or start) to page. This is Confluence's v1 search endpoint — the v2 API has no CQL equivalent.
get_page	confluence:content:read	Get a single Confluence page by numeric id. By default the body is NOT included — pass body-format=storage (or atlas_doc_format) to get the content. The response carries version.number, which you MUST read and increment before calling update_page (optimistic locking).
list_pages	confluence:content:read	List pages, optionally filtered by space id, title, or status. Paginated via the opaque cursor from _links.next.
get_page_children	confluence:content:read	List the direct child pages of a Confluence page (one level). Paginated via cursor.
list_page_labels	confluence:content:read	List the labels attached to a Confluence page.
add_label	confluence:content:write	Add a label to a Confluence page (or other content) by id. Sends a single label object as the body; Confluence also accepts an array but this tool adds one at a time. This is the v1 labels endpoint — v2 has no label-write route.
remove_label	confluence:content:write	Remove a label from a Confluence page by id. The label is passed as the name query parameter (this form tolerates '/' in label names). Reversible by re-adding, so it is not marked always-ask.
list_page_attachments	confluence:content:read	List attachments on a Confluence page (metadata only — title, mediaType, fileSize, downloadLink).
get_attachment	confluence:content:read	Get a single attachment's metadata by id (title, mediaType, fileSize, comment, version, and a downloadLink). Returns metadata, not the binary content.
list_spaces	confluence:space:read	List Confluence spaces the caller can see. Use the returned numeric space id for list_pages/list_space_pages and the key (e.g. DEV) in CQL. Paginated via cursor.
get_space	confluence:space:read	Get a single Confluence space by its numeric id.
list_space_pages	confluence:space:read	List pages in a Confluence space. Paginated via cursor.
list_page_comments	confluence:comments:read	List footer comments on a Confluence page. (Footer comments are the page-level comment thread; inline comments are list_inline_comments.)
list_inline_comments	confluence:comments:read	List root-level inline comments on a Confluence page (comments anchored to a text selection, distinct from footer comments). Paginated via cursor.
get_comment	confluence:comments:read	Get a single footer comment by its id, including its body and version.number (needed to update_comment).
list_page_versions	confluence:content:read	List the version history of a Confluence page (each entry has number, authorId, createdAt, and the change message). Paginated via cursor.
get_folder	confluence:content:read	Get a single Confluence folder by its numeric id (title, parentId, spaceId). Folders are a v2 content type that organise pages within a space.
list_blog_posts	confluence:content:read	List blog posts, optionally filtered by space id, title, or status. Paginated via the opaque cursor from _links.next.
get_blog_post	confluence:content:read	Get a single blog post by numeric id. By default the body is NOT included — pass body-format=storage (or atlas_doc_format) to get the content.
create_page	confluence:content:write	Create a Confluence page. The body uses the storage representation (Confluence XHTML), NOT plain text. Minimal valid shape: {"spaceId": "123456", "status": "current", "title": "My page", "body": {"representation": "storage", "value": "<p>Hello</p>"}}. Get spaceId from list_spaces. To nest under a parent, add "parentId": "<pageId>".
create_blog_post	confluence:content:write	Create a Confluence blog post. Same body caveat as create_page — the body uses the storage representation (Confluence XHTML). Shape: {"spaceId": "123456", "status": "current", "title": "My post", "body": {"representation": "storage", "value": "<p>Hello</p>"}}.
create_folder	confluence:content:write	Create a folder in a Confluence space to organise pages. Shape: {"spaceId": "123456", "title": "My folder"}. To nest under an existing folder or page, add "parentId". Folders are a v2 content type; this needs the write:folder:confluence Atlassian scope.
update_page	confluence:content:write	Update a Confluence page, overwriting its body. OPTIMISTIC LOCKING: call get_page first, read version.number, and pass version:{number: N+1}. The body uses the storage representation (same caveat as create_page). Required fields: id, status, title, body, version. Example: {"id": "123", "status": "current", "title": "My page", "body": {"representation": "storage", "value": "<p>Updated</p>"}, "version": {"number": 4, "message": "edit via agent"}}.
move_page	confluence:content:write	Move a Confluence page relative to another page. position = 'append' makes the page a child of targetId; 'before'/'after' place it as a sibling immediately before/after targetId. Nothing is deleted — the page is relocated — but it overwrites the page's parent, so it is marked a write. This is the v1 content-move endpoint (v2 has no move).
update_comment	confluence:comments:write	Update a footer comment, overwriting its body. OPTIMISTIC LOCKING like update_page: call get_comment first, read version.number, pass version:{number: N+1}. Body uses the storage representation. Shape: {"id": "123", "body": {"representation": "storage", "value": "<p>Edited.</p>"}, "version": {"number": 2}}.
add_comment	confluence:comments:write	Add a footer comment to a Confluence page. Body uses the storage representation. Shape: {"pageId": "123", "body": {"representation": "storage", "value": "<p>Looks good.</p>"}}. To reply to an existing comment, add "parentCommentId".
add_inline_comment	confluence:comments:write	Add an inline comment anchored to a text selection on a page. Shape: {"pageId": "123", "body": {"representation": "storage", "value": "<p>Question.</p>"}, "inlineCommentProperties": {"textSelection": "the exact highlighted text", "textSelectionMatchCount": 1, "textSelectionMatchIndex": 0}}. The textSelection must match text in the page body.
delete_page	confluence:content:delete	Delete a Confluence page by id. By default this moves the page to the trash (restorable); it still removes the page from its space. Needs the delete:page:confluence Atlassian scope.
delete_folder	confluence:content:delete	Delete a Confluence folder by id. Moves the folder to the trash; its contents go with it, so this can remove far more than one page. Needs the delete:folder:confluence Atlassian scope.
delete_comment	confluence:comments:write	Delete a footer comment by id. This is permanent — comments are not trashed like pages. Kept on comments:write (not the content:delete scope) because it removes a single comment, not page content.