OAuth app readiness guide · Docs and knowledge

Getting your Confluence app ready for real users

Tested in a real setup attemptChecked 2026-10-28atlassian.com/software/confluence

Verdict. A private Atlassian OAuth app takes about 5 minutes and no review. Sharing it with customers is self-serve but needs vendor details, policy links and a personal data declaration. For an agent that stores or caches Confluence data, that declaration brings reporting obligations.

At a glance

The answer in one screen

Ease of creation

Easy

About 5 minutes in our test, across three console pages.

Ease of approval

Self-serve

No review to share an OAuth app. Marketplace listing is separate.

Your hands-on time

15 min to 1 day

Minutes for the app; longer if you need a privacy policy and a personal data reporting setup.

Waiting on the provider

None

Sharing takes effect when you save it.

Do you need your own app yet?

Check Composio first.

We could not confirm a Composio-managed Atlassian app.

Watch out: decisions you can't undo

Access type is set at creation. Pick Resource-level unless your agent truly needs every site.
The personal data answer is almost always Yes for agents. Decide your caching and memory design before you share, and plan for the Personal data reporting API.
Stopping sharing affects existing users. Share only when ready to support customers.

Agent an agent can do it You needs you Waiting on the provider

Prerequisites

What to have ready

To create and connect

An Atlassian account; agreement to Atlassian's developer terms
The Composio callback URL (up to 30 callback URLs allowed)

For approval (can take days)

Vendor name, privacy policy URL, terms of service URL, support contact
A personal data decision, and Personal data reporting API handling if Yes

App types

Which one is right for an agent product?

OAuth 2.0 (3LO), not sharing

The default after creation.

Who can install: Only you
Review: None
Use it for: Building and testing

Recommended for agents

OAuth 2.0 (3LO), sharing

After providing vendor and security details.

Who can install: Anyone with your authorization URL
Review: None
Use it for: Agent products with customers

Forge app

Created as a Forge app instead.

Who can install: Installed into sites by admins
Review: Marketplace for distribution
Use it for: Apps that run inside Atlassian

Classic vs granular scopesAtlassian has two scope systems. After adding only classic scopes, the console warned that the Confluence API had no granular scopes. Newer endpoints need granular scopes; mixing them up is a common cause of 401 errors. Tested

Creation steps

Who does what, and how long it takes

YouSign in to developer.atlassian.com
1 min
Console, My apps. A new Developer Space selector may appear.
AgentCreate, OAuth 2.0 integration
1 min
Name the app and choose Resource-level access.
YouAgree to developer terms and create
5 sec
The page notes rotating refresh tokens are mandatory for new apps.
AgentAdd the Confluence API and scopes
2 min
Permissions, Confluence API, Configure, Edit scopes. Choose classic or granular per the endpoints you call.
AgentAdd OAuth 2.0 (3LO) and the callback
1 min
Authorization page, then paste the Composio callback. The page then generates an authorization URL.
YouFill distribution details and share
15 min
Vendor name, policy links, support contact, personal data answer, then switch to Sharing.
YouCopy credentials into Composio
2 min
From the app's Settings page.

In our test: about 5 minutes to a private app with scopes and callback. Sharing was not switched on (needs real policy URLs).

Scopes

What each permission costs you

Scopes are added per API (Confluence, Jira, User identity, Personal data reporting and more). Atlassian recommends no more than 50 scopes in total.

Agent use case	Scopes	What it costs you
Search pages and spaces	`search:confluence`	Classic scope
Read content summaries	`read:confluence-content.summaryread:confluence-space.summary`	Classic scopes
Read full page bodies	`read:confluence-content.all`	Classic scope
Create and edit pages	`write:confluence-content`	Classic scope
Newer v2 endpoints	`granular scopes (e.g. read:page:confluence)`	Required by many newer endpoints
Keep refreshing without the user	`offline_access`	Needed for refresh tokens

Minimal set: "Answer from our wiki" agentsearch:confluenceread:confluence-content.alloffline_access

Check each endpoint's docs for whether it wants granular scopes.

Changing scopes later

Edit scopes on the Permissions page; users must reauthorize to grant new ones.
No review for OAuth apps.

Approval and distribution

Review, cost and renewal

When you need it: No review to share an OAuth 2.0 app. Atlassian Marketplace listing is a separate path. Cost: None to share. Renewal: If you declared personal data: ongoing reporting through the Personal data reporting API.

Immediate

Self-serve, once details are saved.

What you submit

Vendor and security details
Personal data declaration

Common rejection reasons

Not applicable for sharing

Before approval: what works and what's capped

Build and test

Private app, only you.

Limit: Customers cannot authorize until Sharing is on.

First customers

Shared app, any site via your URL.

Limit: Resource-level apps see only the site the user picked.

Scale

Same app.

Limit: Rate limit tier shown on the app; reporting duties if you store personal data.

Data use and compliance

Rules that shape agent design

Personal data declaration. Yes if you store personal data with account IDs or cache data longer than 24 hours.
Personal data reporting. Apps that store personal data report the accounts they hold, so deleted or changed users can be handled.

Design impactAgent memory or a vector index of Confluence pages counts as storing data. Decide this before you share. Tested

Common blockers

Symptom, cause, fix

Symptom	Cause	Fix
401 on newer Confluence endpoints	Only classic scopes added	Add the granular scopes the endpoint documents
Customers cannot authorize	Distribution still Not sharing	Provide vendor details and switch to Sharing
Refresh fails after working once	Rotating refresh token reused	Store the newest refresh token every time
Agent sees only one site	Resource-level access type	Expected; users connect each site, or use Account-level

Sources

Where every claim comes from

Claim	Source
Rotating refresh tokens mandatory for new apps	Tested in our setup
Resource-level vs Account-level access type	Tested in our setup
Apps start private; sharing needs vendor details and personal data declaration	Tested in our setup
Classic vs granular warning	Tested in our setup
Composio managed Atlassian app	Not verified

All sources

Atlassian: OAuth 2.0 (3LO) apps developer.atlassian.com
Atlassian developer console developer.atlassian.com