> ## Documentation Index > Fetch the complete documentation index at: https://docs.serval.com/llms.txt > Use this file to discover all available pages before exploring further. # Confluence > Connect your Atlassian Confluence Cloud site to Serval to mirror spaces and pages into the Knowledge Base and let workflows read and write Confluence content. ## About Confluence Confluence is Atlassian's cloud wiki and documentation product. The Serval Confluence integration connects one Atlassian Cloud site per connection - once connected, Serval mirrors your spaces, pages, and folders into its Knowledge Base and lets workflows act on Confluence with the permissions you grant. Only Confluence Cloud (sites ending in **.atlassian.net**) is supported; Confluence Server and Data Center are not. **Authentication:** Browser-based OAuth 2.0, with two paths - the built-in **Sign in with Confluence (OAuth)** flow (recommended) or a **bring-your-own Atlassian OAuth 2.0 (3LO) app** owned by your organization. Both paths use the same permission picker, and Serval refreshes tokens automatically. **Data sync:** Confluence is a native knowledge source. Serval mirrors spaces, pages, and folder hierarchy into the [Knowledge Base](/sections/documentation/knowledge-base/overview) in the background, including who-can-see-what permissions so agents only answer from pages the requester is allowed to see. Workflow API requests run on demand. ## What the Confluence integration enables | Capability | Description | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Confluence API requests from workflows** | The **Confluence API request** action lets workflows call any part of the Confluence Cloud REST API on your connected site, limited to the permissions you granted. Available from the Confluence integration directly or through the Atlassian umbrella integration. | | **Knowledge Base sync** | Spaces, pages, and folders are mirrored into Serval's Knowledge Base with folder hierarchy preserved. The default permission preset also syncs user, group, and page-restriction information so agent answers respect each page's visibility. Accepting a [knowledge suggestion](/sections/documentation/suggestions/overview) also creates or updates pages in Confluence. | | **Permission presets at connect time** | Two curated presets - **Knowledge Base** (checked by default; read content, search, and resolve user/group permissions) and **Write Pages** (create and update Confluence pages and folders from workflows) - plus an **All permissions** search over the full Confluence permission catalog. | | **Create Confluence Page workflow** | An installable workflow that creates a new page in Confluence with specified content and metadata (installer approval by default). It ships with the Atlassian umbrella integration rather than the standalone Confluence integration. | | **Built-in health checks** | Three connection checks verify authentication, space access, and page access from the integration page. | Anything defined in the [Confluence REST API](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/) can be accessed through Serval. ## Get your credentials Most teams need nothing from Atlassian ahead of time - the recommended path only asks you to sign in and approve access. Creating credentials is only required if your organization wants to use its own Atlassian OAuth app. No Atlassian-side setup. You'll sign in to Atlassian in your browser and approve the permissions Serval requests. All you need is: * An Atlassian account with access to the Confluence Cloud site you're connecting (and the authority to approve app access for it). * Your site's subdomain - the part before **.atlassian.net** in your Confluence address. Confluence Cloud only. Confluence Server and Data Center sites cannot be connected. Choose this if your organization prefers OAuth to run through an app it owns. You'll create an OAuth 2.0 (3LO) integration in the [Atlassian developer console](https://developer.atlassian.com/console/myapps/): Open the [Atlassian developer console](https://developer.atlassian.com/console/myapps/) and create a new OAuth 2.0 (3LO) integration, or open an existing one. Under **Permissions**, add the **Confluence API** and grant every scope you plan to select in Serval's setup dialog. If a scope you pick in Serval isn't granted here, Atlassian will reject the authorization. Under **Authorization**, paste the **Callback URL** shown in Serval's setup form into the Callback URL field. From the integration's **Settings** page, copy the **Client ID** and the **Secret** (click **Show** to reveal it). You'll paste both into Serval. The callback URL must match **exactly**. Copy it from Serval's form using the Copy button - "Register the exact URL Serval provides - a guessed URL will not match the OAuth flow." ## Connect in Serval Open the Confluence integration in Serval and choose **Sign in with Confluence (OAuth)** - it's marked **Recommended** on the selection screen. Type only your subdomain (placeholder: "your-company") - the **.atlassian.net** suffix is shown in the field and added for you. Letters, numbers, and hyphens only, and it can't start or end with a hyphen. If the site is blank or invalid, the form's validation messages are "Confluence site is required" and "Please enter a valid subdomain (letters, numbers, and hyphens only)". Under **Permission Presets** ("Choose from some common use cases"), the **Knowledge Base** preset is checked by default; add **Write Pages** if workflows should create or update pages. The collapsible **All permissions** section lets you "Search the full Confluence permission list (including any scope from presets)". The footer shows "\[number] Confluence permission(s) will be requested." (or "No permissions selected."). At least one permission is required - the Connect button stays disabled until you select one, and submitting without one shows "Select at least one permission." Serval opens Atlassian's consent screen in your browser. Sign in, make sure the correct site is selected, and approve. The consent screen appears on every connect and reconnect. Offline access is always requested automatically on top of your selections - it's how Serval keeps the connection alive without re-prompting you hourly. You can't (and shouldn't) remove it. When you **reconnect**, the site subdomain is prefilled and the picker pre-checks the permissions currently granted, so you only need to add what's missing. On the selection screen, choose **Use your own Atlassian OAuth app** - "Connect with an OAuth 2.0 (3LO) integration owned by your Atlassian workspace." The form shows a read-only **Callback URL** with a **Copy** button (it reads "Loading callback URL..." while it loads, and you can't submit until it appears - "Callback URL is still loading. Wait a moment and try again."). If it fails to load, use **Retry loading callback URL**. Register this exact URL on your Atlassian app before continuing. * **Display name** (optional) - "A friendly name shown in Serval - you choose this." Placeholder: "My Company Confluence". * **Confluence site** (required) - "The subdomain of the Confluence site you're connecting." Same subdomain rules as the standard path. * **Client ID** (required) - "Found on the Settings page of your OAuth 2.0 (3LO) integration." * **Secret** (required) - a password field (placeholder "ATOA..."). "Click Show next to the secret on your integration's Settings page to reveal it." Same picker as the standard path. Every permission you select here must also be granted on your Atlassian app under Permissions, or Atlassian will reject the authorization. Submit, then complete Atlassian's consent screen. You have 10 minutes to finish before the attempt expires and you must restart. The **Secret** is never prefilled. When you reconnect, Serval restores the Display name, Client ID, Confluence site, and permissions - but you must re-enter the Secret every time. If your team has platform-managed OAuth disabled, Serval skips the selection screen and takes you straight to this form - the bring-your-own path is the only one available. Reconnecting an existing bring-your-own connection also opens this form directly. ## Verifying the connection After connecting, run the integration's health checks from the integration page: * **Test Confluence Connection** - confirms Serval can reach your site and authenticate by fetching a small sample of spaces. * Success: "Successfully connected to Confluence" * Failure: "Unable to connect to Confluence. Please verify your API credentials and permissions are correct." * **List Confluence Spaces** - confirms the connection can list spaces. * Success: "Successfully listed spaces from Confluence (sample size: \[number])" * Failure: "Unable to list spaces from Confluence. Please verify your API credentials have permission to view spaces." * **List Confluence Pages** - confirms the connection can list current pages. * Success: "Successfully listed pages in Confluence (sample: \[number])" * Failure: "Unable to search content in Confluence. Please verify your API credentials have permission to search and read content." All three checks only need read access to spaces and pages - they can pass even if the connection is missing the user, group, and restriction permissions that Knowledge Base sync uses to resolve page visibility. If health checks are green but synced answers ignore page restrictions or sync seems incomplete, reconnect and make sure the full **Knowledge Base** preset is checked. ## Gotchas and troubleshooting Serval matches the site you authorized in Atlassian against the subdomain you entered (your input is matched case-insensitively). If they don't match, the connection fails with "target Confluence site '\[subdomain].atlassian.net' not found in accessible resources. Please ensure you have access to this site and selected it during authorization". If your Atlassian account has no authorized sites at all, you'll see "no accessible Confluence sites found". And if no subdomain reaches the server, exactly one authorized site is required - otherwise the attempt fails with "multiple Confluence sites found (\[number]). Please specify which site to connect by providing the subdomain". Double-check the subdomain and make sure you select the right site on Atlassian's consent screen. Permissions are baked into the OAuth consent and stored on the connection. To add permissions (for example, enabling **Write Pages** after the fact), reconnect the integration - the picker pre-checks what's already granted so you only add what's missing. Atlassian's consent screen is shown every time by design. The permissions you select in Serval are requested verbatim from your app. If any selected permission isn't granted on the Atlassian OAuth 2.0 (3LO) integration under Permissions, Atlassian rejects the authorization. As the setup form puts it: "Make sure your integration grants at least these scopes under Permissions." Atlassian requires an exact match between the callback URL registered on your app and the one Serval uses. Always copy the value from Serval's form - "Register the exact URL Serval provides - a guessed URL will not match the OAuth flow." If the form ever shows "Server returned an empty callback URL", retry loading it before submitting. Your app details are held securely for only 10 minutes between submitting the Serval form and completing Atlassian's consent screen. Taking longer fails with "Invalid or expired OAuth state" - restart the connect flow and complete the consent promptly. On reconnect, Serval prefills the Display name, Client ID, Confluence site, and permissions - but the Secret field is always blank and required. There is no keep-the-existing-secret option; have the Secret handy (or reveal it again in the Atlassian developer console) before reconnecting. Both connection paths automatically request offline access so Atlassian issues a refresh token; without it, the connection would die when the one-hour access token expires. If a bring-your-own connection ends up without a refresh token, requests fail with "custom Confluence OAuth app access token expired and no refresh token available; reconnect required" - reconnect to fix it. The connect form appends **.atlassian.net** to your subdomain, and all traffic goes through Atlassian's cloud API. Confluence Server and Data Center deployments cannot be connected. If your team has platform-managed OAuth disabled, Serval sends you directly to the bring-your-own-app form and the Back button to the selection screen is disabled. That's expected - only the bring-your-own path is available in that configuration. The Confluence API request action requires the request path to begin with a forward slash. If it doesn't, the request fails with 'Confluence API path must start with "/" (e.g. "/wiki/api/v2/..."); got: \[path]'. Have your workflow builder copy the full path exactly as it appears in Atlassian's REST API documentation, including the leading slash - Serval adds the site-specific prefix for your connected site automatically. *** Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Confluence integration.