Skip to content
API Reference
Admin /Catalog /API Servers
Confluence logo

Confluence

Productivity

Access Confluence pages, spaces, and content

Atlassian developer consoleOAuth setup guideAPI docs

Adding Confluence provisions a resource (the upstream Atlassian API at https://api.atlassian.com/ex/confluence, with default scopes pre-set) and a provider for Atlassian’s OAuth issuer - auto-provisioned on first install, or reused if you already connected another Atlassian resource.

Your application calls Keycard’s token-exchange endpoint with the user’s identity, gets back a token scoped to this resource, and uses it to call Atlassian directly. Identity, policy, and audit log apply to every exchange - the OAuth client secret stays inside Keycard. Each exchange is recorded in the audit log with the user identity, the resource accessed, and the policy decision.

Scopes

Section titled “Scopes”
SCOPES

OAuth permissions Keycard requests on install. Override or add scopes in Console.

read:confluence-content.all
default
write:confluence-content
default
read:confluence-content.summary
read:confluence-content.permission
read:confluence-space.summary
write:confluence-space
write:confluence-file
readonly:content.attachment:confluence
read:confluence-props
write:confluence-props
read:confluence-user
read:confluence-groups
write:confluence-groups
manage:confluence-configuration
search:confluence

Use Confluence from your code

Section titled “Use Confluence from your code”
USE FROM CODE

Call Confluence from your application with a Keycard-issued token scoped to this resource.

After installing Confluence, your application exchanges a Keycard-issued access token for a token scoped to this resource. Pass the user’s access token as the subject_token.

from keycardai.oauth import Client, BasicAuth, TokenType
import requests


# Exchange the user's Keycard token for a Confluence token.
with Client(
    "https://<zone-id>.keycard.cloud",
    auth=BasicAuth("<your-client-id>", "<your-client-secret>"),
) as client:
    response = client.exchange_token(
        subject_token=user_access_token,
        subject_token_type=TokenType.ACCESS_TOKEN,
        resource="https://api.atlassian.com/ex/confluence",
    )


# Call Confluence directly with the exchanged token.
r = requests.get(
    "https://api.atlassian.com/ex/confluence/<endpoint>",
    headers={"Authorization": f"Bearer {response.access_token}"},
)

See the OAuth SDK → Token Exchange reference for the full client API.

Setup

Section titled “Setup”
SETUP

Register your OAuth credentials with Keycard so the resource can issue tokens.

Create an Atlassian OAuth app

Section titled “Create an Atlassian OAuth app”
  1. Go to the Atlassian Developer Console
  2. Click Create → OAuth 2.0 integration
  3. Enter a name for your integration
  4. Click Create

Configure Confluence permissions

Section titled “Configure Confluence permissions”
  1. Go to Permissions in your app settings
  2. Find Confluence and click Add
  3. Configure the scopes:
    • read:confluence-content.all - Read Confluence content
    • write:confluence-content - Create and edit pages

Set the callback URL

Section titled “Set the callback URL”
  1. Go to Authorization in your app settings
  2. Click Add next to OAuth 2.0 (3LO)
  3. Enter the redirect URI provided by Keycard as the Callback URL

Get credentials

Section titled “Get credentials”
  1. Go to Settings in your app
  2. Note the Client ID and Secret

Register in Keycard

Section titled “Register in Keycard”
  1. Open Keycard Console → your zone → Resources
  2. Click Explore Resources
  3. Find and click Confluence in the catalog
  4. In the configuration dialog:
    • If this is your first Atlassian resource, copy the Redirect URL and verify it’s set as the callback URL in your Atlassian OAuth app. Enter the Client ID and Secret from your app settings.
    • Review the User scopes - the defaults (read:confluence-content.all, write:confluence-content) are pre-populated
  5. Click Add Confluence API

Troubleshooting

Section titled “Troubleshooting”
TROUBLESHOOTING

Common errors when wiring Confluence into your zone.

Empty accessible-resources response

The user hasn’t granted access to any Atlassian sites. During the OAuth consent flow, ensure you select at least one site. If re-authorizing, you may need to revoke and re-grant access.

Error 401: Unauthorized

The token is invalid or expired. Atlassian tokens expire after a short period. Reconnect the provider in Keycard Console - Keycard will handle the refresh if a refresh token was issued.

Error: consent_required

The app’s permissions were updated after the user last authorized it. The user needs to re-authorize to grant the new scopes. Remove the provider connection and connect again.

Section titled “Related”
RELATED