Skip to content

docs: improve confluence docs #5049

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hassan254-prog merged 5 commits into from
Jan 7, 2026
Merged

docs: improve confluence docs #5049

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c264fc1
docs: improve docs
hassan254-prog Nov 21, 2025
dbc0be6
grammar
hassan254-prog Nov 21, 2025
7736352
Merge branch 'master' into wari/confluence-docs
hassan254-prog Jan 6, 2026
13f104d
fixes after merging
hassan254-prog Jan 6, 2026
0a91690
remove unused doc page
hassan254-prog Jan 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified docs/integrations/all/apollo/form.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
290 changes: 161 additions & 129 deletions docs/integrations/all/confluence.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,136 +1,168 @@
---
title: Confluence
sidebarTitle: Confluence
title: 'Confluence'
sidebarTitle: 'Confluence'
description: 'Access the Confluence API in 2 minutes 💨'
---

import Overview from "/snippets/overview.mdx"
import PreBuiltTooling from "/snippets/generated/confluence/PreBuiltTooling.mdx"
import PreBuiltUseCases from "/snippets/generated/confluence/PreBuiltUseCases.mdx"

import { StatusWidget } from "/snippets/api-down-watch/status-widget.jsx"

<StatusWidget service="confluence" />

<Overview />
<PreBuiltTooling />
<PreBuiltUseCases />

## Access requirements
| Pre-Requisites | Status | Comment|
| - | - | - |
| Paid dev account | ✅ Not required | Free, self-signup for an [Atlassian developer account](https://developer.atlassian.com/). |
| Paid test account | ✅ Not required | Free Confluence Cloud instance can be used for testing. |
| Partnership | ✅ Not required | |
| App review | ⚠️ Conditional | Required only if you want to list your app on the Atlassian Marketplace. |
| Security audit | ✅ Not required | |


## Setup guide

<Steps>
<Step title="Create an Atlassian developer account">
If you don't already have one, sign up for an [Atlassian developer account](https://id.atlassian.com/signup/).
</Step>
<Step title="Create a new OAuth 2.0 (3LO) app">
1. Go to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/).
2. Click **Create** and select **OAuth 2.0 integration**.
3. Enter a name, agree to Atlassian's developer terms by checking the agreement checkbox for your app and click **Create**.
4. Your app will be created and you'll be taken to the app management page.
</Step>
<Step title="Configure OAuth 2.0 (3LO)">
1. In the left sidebar, select **Authorization**.
2. Next to OAuth 2.0 (3LO), click **Add**.
3. Enter `https://api.nango.dev/oauth/callback` as the Callback URL.
4. Click **Save** to save your changes.
</Step>
<Step title="Add API permissions">
1. In the left sidebar, select **Permissions**.
2. Find the Confluence API and click **Add**, and then click **Configure**.
3. Click **Edit Scopes** then select the scopes your application requires. Common scopes include:
- `read:confluence-user` - Read user information
- `read:confluence-content.all` - Read all content
- `read:confluence-content.summary` - Read content summaries
- `write:confluence-content` - Create and update content
- `delete:confluence-content` - Delete content
- `manage:confluence-configuration` - Manage Confluence instance settings
- `offline_access` - Get refresh tokens (required for long-term access)
4. Click **Save** to save your changes.
</Step>
<Step title="Obtain your client credentials">
1. In the left sidebar, select **Settings**.
2. Note your **Client ID**.
3. Copy both the Client ID and Secret by clicking the copy buttons next to them, as you'll need them when configuring your integration in Nango.
</Step>
<Step title="Make your app available to users (optional)">
If you want to distribute your app to other users:

1. In the left sidebar, select **Distribution**.
2. In **Distribution controls**, click the **Edit** button, then select the **Sharing** radio button.
3. Return to the Authorization page and copy the Authorization URL to share with your users.

Note: By default, your app is private and can only be used by you. Making it public allows other users to authorize your app.
</Step>
<Step title="Next">
Follow the [_Quickstart_](/getting-started/quickstart).
</Step>
</Steps>

<Tip>Need help getting started? Get help in the [community](https://nango.dev/slack).</Tip>


## Useful links

| Topic | Links |
| - | - |
| General | [Atlassian Developer Portal](https://developer.atlassian.com/) |
| | [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) |
| | [Confluence Cloud Platform Documentation](https://developer.atlassian.com/cloud/confluence/) |
| Developer | [OAuth 2.0 (3LO) Apps Documentation](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/) |
| | [OAuth Scopes Reference](https://developer.atlassian.com/cloud/confluence/scopes-for-oauth-2-3LO-and-forge-apps/) |
| | [Confluence REST API Documentation](https://developer.atlassian.com/cloud/confluence/rest/intro/) |
| | [API Rate Limits](https://developer.atlassian.com/cloud/confluence/rate-limiting/) |
| | [Basic Auth Documentation](https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis/) |
| | [Distributing OAuth 2.0 Apps](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/#distributing-your-oauth-2-0--3lo--apps) |
| | [Atlassian Marketplace](https://marketplace.atlassian.com/) |

<Note>Contribute useful links by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/confluence.mdx)</Note>

## Common Scopes

| Scope | Description |
| ----- | ----------- |
| read:confluence-user | Read user information |
| read:confluence-content.all | Read all Confluence content |
| write:confluence-content | Create and update Confluence content |
| offline_access | Access to refresh tokens for offline access |



## API gotchas

- To allow the possibility of refreshing the token, you must add `offline_access` to your scopes when creating the integration on the Nango UI.
- When connecting to Confluence, you have two options for specifying which Confluence site to connect to:
1. Provide a `domain` during connection creation (recommended): This ensures you connect to the specific Confluence site you want.
2. Let Nango auto-select the first available site (legacy behavior): If no baseUrl is specified, Nango will use the first site from the accessible resources api.
- You will need to fetch your Cloud ID to be able to make API requests to the Confluence API. You can do this with the proxy by calling:


```ts
const response = await nango.get({
endpoint: `oauth/token/accessible-resources`,
baseUrlOverride: 'https://api.atlassian.com'
});
const cloudId = response.data[0].id;
```

You can then construct your URL as follows: `https://api.atlassian.com/ex/confluence/${cloudId}/wiki/rest/api/<endpoint>`

- When you create an OAuth 2.0 (3LO) app, it's private by default. Before using the integration, you must make your app public. If you want to make your app public, find the how-to [here](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#distributing-your-oauth-2-0--3lo--apps).
- Refresh tokens will expire after 365 days of non use and will expire by 90 days if the resource owner is inactive for 90 days. Make sure you call `nango.getConnection()` at least every 365 days to trigger a refresh. See reference [here](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#how-do-i-get-a-new-access-token--if-my-access-token-expires-or-is-revoked-).
- The `state` parameter is required for security in the OAuth flow to prevent CSRF attacks. Nango handles this automatically.
- Confluence's OAuth implementation uses rotating refresh tokens. Each time you refresh an access token, you'll receive a new refresh token that invalidates the previous one.
- When making API calls, remember that the permissions of the user who authorized your app will limit what your app can do, regardless of the scopes you've requested.
- Confluence and Jira share the same OAuth infrastructure, so the OAuth setup process is identical for both products.
- The Confluence REST API has different versions. Make sure you're using the correct version for your needs.

<Note>Contribute API gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/confluence.mdx)</Note>
<Tabs>
<Tab title="🚀 Quickstart">
<Steps>
<Step title="Create an integration">
In Nango ([free signup](https://app.nango.dev)), go to [Integrations](https://app.nango.dev/dev/integrations) -> _Configure New Integration_ -> _Confluence_. Nango doesn't provide a test OAuth app for Confluence yet. You’ll need to set up your own by following these [instructions](#🧑%E2%80%8D💻-oauth-app-setup). After that, make sure to add the OAuth client ID, secret, and scopes in the integration settings in Nango.
</Step>
<Step title="Authorize Confluence">
Go to [Connections](https://app.nango.dev/dev/connections) -> _Add Test Connection_ -> _Authorize_, then log in to Confluence. Later, you'll let your users do the same directly from your app.
</Step>
<Step title="Call the Confluence API">
Let's make your first request to the Confluence API (fetch a list of pages). Replace the placeholders below with your [secret key](https://app.nango.dev/dev/environment-settings), [integration ID](https://app.nango.dev/dev/integrations), and [connection ID](https://app.nango.dev/dev/connections):
<Tabs>
<Tab title="cURL">
```bash
curl "https://api.nango.dev/proxy/ex/confluence/{connectionConfig.cloudId}/wiki/api/v2/pages?limit=10" \
-H "Authorization: Bearer <NANGO-SECRET-KEY>" \
-H "Provider-Config-Key: <INTEGRATION-ID>" \
-H "Connection-Id: <CONNECTION-ID>"
```
</Tab>

<Tab title="Node">

Install Nango's backend SDK with `npm i @nangohq/node`. Then run:

```typescript
import { Nango } from '@nangohq/node';

const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });

const res = await nango.get({
endpoint: '/ex/confluence/{connectionConfig.cloudId}/wiki/api/v2/pages',
params: {
limit: 10
},
providerConfigKey: '<INTEGRATION-ID>',
connectionId: '<CONNECTION-ID>'
});

console.log(JSON.stringify(res.data, null, 2));
```
</Tab>

</Tabs>

Or fetch credentials dynamically via the [Node SDK](/reference/sdks/node#get-a-connection-with-credentials) or [API](/reference/api/connection/get).

<Note>
The `{connectionConfig.cloudId}` in the URL represents the cloudId. You can get this value from your connection configuration after creating the connection. The cloudId is automatically set by Nango.
</Note>

</Step>
</Steps>

✅ You're connected! Check the [Logs](https://app.nango.dev/dev/logs) tab in Nango to inspect requests.

<Tip>
Next step: [Embed the auth flow](/getting-started/quickstart/embed-in-your-app) in your app to let your users connect their Confluence accounts.
</Tip>
</Tab>
<Tab title="🧑‍💻 OAuth app setup">
<Steps>
<Step title="Create an Atlassian developer account">
If you don't already have one, sign up for an [Atlassian developer account](https://id.atlassian.com/signup/).
</Step>
<Step title="Create a new OAuth 2.0 (3LO) app">
1. Go to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/).
2. Click **Create** and select **OAuth 2.0 integration**.
3. Enter a name, agree to Atlassian's developer terms by checking the agreement checkbox for your app and click **Create**.
4. Your app will be created and you'll be taken to the app management page.
</Step>
<Step title="Configure OAuth 2.0 (3LO)">
1. In the left sidebar, select **Authorization**.
2. Next to OAuth 2.0 (3LO), click **Add**.
3. Enter `https://api.nango.dev/oauth/callback` as the **Callback URL**.
4. Click **Save Changes** to save your changes.
</Step>
<Step title="Add API permissions">
1. In the left sidebar, select **Permissions**.
2. Find the Confluence API and click **Add**, and then click **Configure**.
3. Click **Edit Scopes** then select the [scopes](https://developer.atlassian.com/cloud/confluence/scopes-for-oauth-2-3LO-and-forge-apps/) your application requires. For reference, see our [Common Scopes](#common-scopes) table below.
4. Click **Save** to save your changes.
</Step>
<Step title="Obtain your client credentials">
1. In the left sidebar, select **Settings**.
2. Note your **Client ID**.
3. Copy both the **Client ID** and **Secret** by clicking the copy buttons next to them, as you'll need them when configuring your integration in Nango.
</Step>
<Step title="Make your app available to users">
1. In the left sidebar, select **Distribution**.
2. In **Distribution controls**, click the **Edit** button, select the **Sharing** radio button, enter a **Privacy Policy URL** and then click the **Save changes** button.
<Note>By default, your app is private and can only be used by you. Making it public allows other users to authorize your app.</Note>
</Step>
<Step title="Next">
Follow the [_Quickstart_](/getting-started/quickstart).
</Step>
</Steps>

## Common Scopes

| Scope | Description |
| --------------------------------- | ------------------------------------------------- |
| `read:confluence-user` | Read user information |
| `read:confluence-content.all` | Read all content |
| `read:confluence-content.summary` | Read content summaries |
| `write:confluence-content` | Create and update content |
| `delete:custom-content:confluence`| Delete content |
| `read:confluence-space.summary` | Read space summaries |
| `write:space:confluence` | Create or update spaces |
| `offline_access` | Access refresh tokens for offline use |
| `read:space:confluence` | Read Confluence spaces (required for spaces sync) |
| `read:page:confluence` | Read Confluence pages (required for pages sync) |


</Tab>
<Tab title="🔗 Useful links">
| Topic | Links |
| - | - |
| General | [Atlassian Developer Portal](https://developer.atlassian.com/) |
| | [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) |
| | [Confluence Cloud Platform Documentation](https://developer.atlassian.com/cloud/confluence/) |
| Developer | [OAuth 2.0 (3LO) Apps Documentation](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/) |
| | [OAuth Scopes Reference](https://developer.atlassian.com/cloud/confluence/scopes-for-oauth-2-3LO-and-forge-apps/) |
| | [Confluence REST API Documentation](https://developer.atlassian.com/cloud/confluence/rest/intro/) |
| | [API Rate Limits](https://developer.atlassian.com/cloud/confluence/rate-limiting/) |
| | [Basic Auth Documentation](https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis/) |
| | [Distributing OAuth 2.0 Apps](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/#distributing-your-oauth-2-0--3lo--apps) |
| | [Atlassian Marketplace](https://marketplace.atlassian.com/) |

<Note>Contribute useful links by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/confluence.mdx)</Note>
</Tab>
<Tab title="🚨 API gotchas">
- Refreshing tokens requires the `offline_access` scope when creating the integration.
- When connecting to Confluence, you have two options for specifying which Confluence site to connect to:
1. Provide a `domain` during connection creation (recommended): This ensures you connect to the specific Confluence site you want.
2. Let Nango auto-select the first available site (legacy behavior): If no baseUrl is specified, Nango will use the first site from the accessible resources api.

- A single Confluence OAuth token can be valid for multiple Atlassian sites. For example, the same token might grant access to both "nango-hq.atlassian.net" and "nango-test.atlassian.net". This is why specifying the `domain` during connection creation is important if you need to connect to a specific site.

- The connection process works as follows:
1. Nango fetches all accessible sites for the OAuth token
2. If you specified a `domain`, Nango finds the matching site and sets its `cloudId`
3. If no `domain` is specified, Nango uses the first available site and sets its `cloudId`
4. The selected site's `cloudId` and `domain` are stored in the connection configuration

- When you create an OAuth 2.0 (3LO) app, it's private by default. Before using the integration, you must make your app public. If you want to make your app public, find the how-to [here](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/#distributing-your-oauth-2-0--3lo--apps).
- Refresh tokens will expire after 365 days of non-use and will expire by 90 days if the resource owner is inactive for 90 days. Make sure you call `nango.getConnection()` at least every 365 days to trigger a refresh. See reference [here](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/#how-do-i-get-a-new-access-token--if-my-access-token-expires-or-is-revoked-).
- Confluence's OAuth implementation uses rotating refresh tokens. Each time you refresh an access token, you'll receive a new refresh token that invalidates the previous one.
- When making API calls, remember that the permissions of the user who authorized your app will limit what your app can do, regardless of the scopes you've requested.
- The Confluence REST API has different versions. Make sure you're using the correct version for your needs.

<Note>Contribute API gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/confluence.mdx)</Note>
</Tab>
</Tabs>

<Info>
Questions? Join us in the [Slack community](https://nango.dev/slack).
</Info>
2 changes: 1 addition & 1 deletion docs/integrations/all/facebook.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ import { StatusWidget } from "/snippets/api-down-watch/status-widget.jsx"
<Note>Contribute useful links by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/facebook.mdx)</Note>
</Tab>
<Tab title="🚨 API gotchas">
_No reported gotchas._
- Facebook tokens expire after 60 days and cannot be refreshed. Once a token expires, users must re-authenticate by [re-authorizing the connection](/implementation-guides/api-auth/implement-api-auth#6-re-authorize-an-existing-connection).

<Note>Contribute API gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/facebook.mdx)</Note>
</Tab>
Expand Down
2 changes: 1 addition & 1 deletion docs/snippets/generated/pennylane-company-api/PreBuiltTooling.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
| - | - |
| Create or customize use-cases | ✅ |
| Pre-configured pagination | 🚫 (time to contribute: &lt;48h) |
| Pre-configured rate-limit handling | 🚫 (time to contribute: &lt;48h) |
| Pre-configured rate-limit handling | ✅ |
| Per-customer configurations | ✅ |
</Accordion>
</AccordionGroup>
2 changes: 1 addition & 1 deletion docs/snippets/generated/pennylane/PreBuiltTooling.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
| - | - |
| Create or customize use-cases | ✅ |
| Pre-configured pagination | 🚫 (time to contribute: &lt;48h) |
| Pre-configured rate-limit handling | 🚫 (time to contribute: &lt;48h) |
| Pre-configured rate-limit handling | ✅ |
| Per-customer configurations | ✅ |
</Accordion>
</AccordionGroup>
Loading
Loading