Skip to main 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; self-hosted Confluence uses the separate Confluence Data Center integration. 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 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

Anything defined in the Confluence REST API 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. For a self-hosted Data Center site, use the Confluence Data Center integration.

​
Connect in Serval

1

Choose the recommended option

Open the Confluence integration in Serval and choose Sign in with Confluence (OAuth) - it’s marked Recommended on the selection screen.
2

Enter your Confluence site (required)

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)”.
3

Choose Permission Presets (required)

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

Approve in Atlassian

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.

​
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. For a self-hosted Data Center site, use the Confluence Data Center integration.
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 for assistance with your Confluence integration.