Confluence Data Center

Confluence Data Center is the self-hosted, on-premises version of Confluence for enterprise teams who need more control, security, and scalability for their documentation and collaboration needs.

For the hosted product, use Confluence instead.

Authentication Types

Confluence Data Center supports 3 authentication methods:

• OAuth 2.0 - Use OAuth 2.0 authentication with your self-hosted Confluence Data Center instance (requires v7.17 or later).

  • Pros: Secure, per-user tracking, production-ready, no credentials stored in Willow
  • Cons: Requires OAuth configuration on Confluence Data Center

• API Key - Use a personal access token for authentication.

  • Pros: Simple setup
  • Cons: Single credential for all users

• API Key Per User - Each user provides their own personal access token.

  • Pros: Per-user tracking, audit trail
  • Cons: Each user must generate their own token

Configuration

Before using the connector, you need to configure:

• Confluence Organization Domain - Your Confluence Data Center instance URL (e.g., https://confluence.company.com)

Setting up OAuth 2.0

OAuth 2.0 is available for self-hosted Confluence Data Center instances running version 7.17 or later.

Requirements:

• Confluence Data Center v7.17 or later
• HTTPS enabled on your Confluence instance (required for production)
• Administrator access to Confluence Data Center

Setup Steps:

1. Log in to your Confluence Data Center instance as an administrator

2. Navigate to Settings (gear icon) → General Configuration → Application links

3. Click Create link

4. Select External application and then Incoming

5. Choose OAuth 2.0 as the authentication method

6. Configure the OAuth application:

   • Name: Enter a descriptive name (e.g., "Willow Integration")
   • Redirect URL:
     • For SaaS deployments: https://{org}.mcp-s.com/{org}/api/auth/callback
     • For On-Premise deployments: {connectUrl}/{org}/api/auth/callback
   • Scopes: Enable the required scopes:
     • READ - View content and spaces
     • WRITE - Create, update, and delete content (includes READ)
     • ADMIN - Administrative operations (includes WRITE and READ)
     • SYSTEM_ADMIN - System-level administration (includes all other scopes)
     • MANAGE_SUBSCRIPTIONS - Manage user subscriptions and notifications

7. Click Save and copy the Client ID and Client Secret

8. In Willow:

   • Paste the Client ID and Client Secret
   • Enter your Confluence Data Center instance URL in Confluence Organization Domain (e.g., https://confluence.company.com)

9. Click Save Changes and authorize

Additional Information:

• For detailed configuration steps, see Atlassian's official documentation
• OAuth 2.0 supports both Authorization Code and Authorization Code with PKCE flows
• PKCE is enabled by default for enhanced security
• Access tokens expire after 2 hours by default and are automatically refreshed

Generating a Personal Access Token

For Confluence Data Center (version 8.0+):

1. Log in to your Confluence Data Center instance

2. Click on your profile icon in the top right

3. Go to Settings

4. In the left sidebar, click Personal Access Tokens

5. Click Create token

6. Enter a Token name and optionally set an expiry date

7. Click Create

8. Copy the token immediately (it won't be shown again)

9. Paste the token into Willow

10. Enter your Confluence Organization Domain in Configuration

Note: For Confluence Data Center versions before v8.0, personal access tokens are not available. You will need to use OAuth 2.0 authentication instead.

Available Scopes

Confluence Data Center uses a simplified scope system compared to Confluence Cloud:

Scope	Description	Permissions
READ	Read-only access	View pages, spaces, comments, attachments, and metadata
WRITE	Read and write access	Includes READ + create, update, delete content
ADMIN	Administrative access	Includes WRITE + space administration, user management
SYSTEM_ADMIN	System administration	Includes all permissions above + system configuration
MANAGE_SUBSCRIPTIONS	Subscription management	Manage user notifications and watchers

Scope Hierarchy:

• SYSTEM_ADMIN > ADMIN > WRITE > READ
• Higher scopes include all permissions from lower scopes

Recommended Scopes:

• For most integrations: READ and WRITE
• For administrative operations: Add ADMIN
• For system-level management: Use SYSTEM_ADMIN (be cautious - this grants full access)

Available Tools

The Confluence Data Center connector provides the following tools:

Content Operations

• Search Content - Search for pages, blog posts, and other content using CQL (Confluence Query Language)
• Get Page - Retrieve a specific page with its content
• List Pages in Space - List all pages in a specific space
• Create Page - Create a new page in a space
• Update Page - Update an existing page
• Delete Page - Delete a page
• Get Child Pages - Get child pages of a parent page

Space Operations

• List Spaces - List all available spaces
• Get Space - Get details of a specific space
• Get Space Properties - Get custom properties for a space

Comment Operations

• Get Comments - Get comments on a page
• Add Comment - Add a comment to a page

Label Operations

• Get Labels - Get labels for a page
• Add Labels - Add labels to a page

Attachment Operations

• Get Attachments - Get attachments for a page
• Upload Attachment - Upload a file to a page

Blog Operations

• Create Blog Post - Create a new blog post in a space

Metadata Operations

• Get Content History - Get version history of a page
• Get Content Properties - Get custom properties for a page
• Set Content Property - Set a custom property on a page

Permission Operations

• Get Page Restrictions - Get access restrictions for a page
• Update Page Restrictions - Update who can read or edit a page
• Watch Page - Add current user as a watcher of a page

Troubleshooting

OAuth 2.0 Issues

Problem: "OAuth application not found" error

Solution:

• Verify the Client ID and Client Secret are correct
• Ensure the OAuth application is configured as "Incoming" in Application Links
• Check that the Redirect URL matches exactly (including trailing slashes)

Problem: "Insufficient scope" error

Solution:

• Verify the required scopes are enabled in the OAuth application configuration
• Remember that WRITE includes READ, and ADMIN includes both
• Re-authorize the application after changing scopes

Problem: "Invalid redirect URI" error

Solution:

• Copy the exact Redirect URL from Willow (don't type it manually)
• Ensure there are no extra spaces or characters
• Some Confluence versions are case-sensitive for redirect URLs

Personal Access Token Issues

Problem: "Personal Access Tokens option not available"

Solution:

• PATs are only available in Confluence Data Center v8.0+
• Check your Confluence version in Settings → System Info
• If on an older version, use OAuth 2.0 instead

Problem: "401 Unauthorized" with PAT

Solution:

• Verify the token was copied correctly
• Check if the token has expired (if you set an expiry date)
• Ensure your Confluence Organization Domain is correct
• Verify the token belongs to a user with appropriate permissions

Connection Issues

Problem: "Cannot connect to Confluence instance"

Solution:

• Verify the Organization Domain is correct (e.g., https://confluence.company.com)
• Don't include /wiki or other paths in the domain
• Ensure HTTPS is used (HTTP may not work for OAuth)
• Check that the instance is accessible from Willow (no firewall blocking)

Problem: "SSL certificate verification failed"

Solution:

• Ensure your Confluence instance has a valid SSL certificate
• Self-signed certificates may cause issues
• Contact your IT team if using a corporate proxy or firewall

API Issues

Problem: "REST API not enabled"

Solution:

• The REST API is enabled by default in Confluence Data Center
• Check Settings → General Configuration → Administration
• Ensure "Remote API" is enabled

Problem: "Permission denied" errors

Solution:

• Verify the authenticated user has appropriate space permissions
• Check space permissions in Space Settings → Permissions
• Some operations require space admin or system admin rights

API Differences from Confluence Cloud

If you're migrating from Confluence Cloud, note these differences:

Aspect	Confluence Cloud	Confluence Data Center
Base Path	/wiki/rest/api	/rest/api
OAuth URL	auth.atlassian.com	{your-domain}/rest/oauth2/latest
Scopes	90+ granular scopes	5 simplified scopes
API Format	Same REST API structure	Same REST API structure
CQL	Supported	Supported
Rate Limiting	Automatic	Instance-dependent

Best Practices

1. Use OAuth 2.0 for production - It's more secure and provides per-user tracking
2. Request minimal scopes - Only request READ/WRITE unless you need administrative access
3. Use CQL for searching - The Search Content tool with CQL is very powerful for finding content
4. Handle pagination - Many list operations return paginated results; use limit and start parameters
5. Check permissions first - Use Get Page Restrictions before attempting restricted operations
6. Use content properties for metadata - Store custom metadata using content properties instead of comments
7. Monitor token expiry - Set expiry dates on Personal Access Tokens to enhance security

Additional Resources

• Confluence Data Center REST API Documentation
• CQL (Confluence Query Language) Reference
• Application Links Configuration
• Confluence Data Center Documentation

Support

For issues specific to:

• Willow integration: Contact Willow support
• Confluence Data Center setup: Contact your Confluence administrator
• OAuth configuration: Refer to Atlassian's Application Links documentation
• API behavior: Consult the Confluence REST API documentation