Confluence Integration Setup

Prerequisites

• A Confluence Cloud site (e.g., acme.atlassian.net). Confluence Data Center and Server are not supported
• An Atlassian account with access to that site to authorize the connection, and access to the Atlassian developer console to create the app
• ZLH running with a reachable callback URL

Step 1: Create an OAuth 2.0 Integration in the Atlassian Developer Console

1. Go to developer.atlassian.com/console/myapps and click Create > OAuth 2.0 integration
2. Name it ZombieLicenseHunter, accept the terms and create it
3. Under Permissions, find Confluence API, click Add, then Configure, and add these classic scopes:
   • read:confluence-user — read user accounts and email addresses
   • search:confluence — list users through the search API
4. Under Authorization, next to OAuth 2.0 (3LO) click Add and set the Callback URL to {YOUR_ZLH_BASE_URL}/integrations/confluence/callback
5. Under Settings, copy the Client ID and Secret

Atlassian may warn on the consent screen that the app has not been reviewed. That is expected for a private integration.

Step 2: ZLH-Side Values

• The Callback URL must be exactly {YOUR_ZLH_BASE_URL}/integrations/confluence/callback — protocol, host, port and path
• Scopes requested: read:confluence-user search:confluence offline_access. The first two must be added under Permissions in Step 1; offline_access is a token-refresh scope that Atlassian grants without configuration. Self-hosted deployments can override the list with CONFLUENCE_SCOPES
• The Client ID and Secret are entered per integration in the UI, not in environment variables

Step 3: Connect via the ZLH UI

1. In ZLH, navigate to Integrations > Add Integration
2. Select Confluence
3. Enter the Client ID and Client Secret from Step 1
4. Enter your Confluence Site URL as the site host, e.g. acme.atlassian.net (https://acme.atlassian.net also works). No path, port or query string
5. Click Connect — you are redirected to Atlassian to sign in
6. On the consent screen choose the site that matches the URL you entered and click Accept
7. You are redirected back to ZLH with the integration active and a first sync queued

After consent, ZLH checks that the site you entered is one the authorizing account can reach with Confluence. One integration covers one site; connect each site separately.

What Gets Synced

ZLH lists users through the Confluence search API (type=user), 50 per page. Only Atlassian user accounts are imported; app and customer (portal) accounts are skipped. For each user it captures:

• Atlassian account ID (used as the stable identifier) and email address
• Public name
• Active status — the search API returns active users only, so every imported user is active
• License type, recorded as confluence

Confluence does not expose login timestamps, so last-login data is not available. Users who hide their email in their Atlassian profile are imported with an account ID only and show as unmatched. A self-hosted deployment configured with an Atlassian organization admin API key (JIRA_ORG_ID and JIRA_ORG_ADMIN_API_KEY) backfills those emails and records whether each account is managed by your organization.

Troubleshooting