[Confluence Cloud] api.atlassian.com users get 401 'scope does not match' with default wiki/api/v2 settings

[Zircoz]

Description

Users accessing Confluence Cloud via the OAuth2 API gateway (https://api.atlassian.com/ex/confluence/<tenant-id>) get a 401 Unauthorized; scope does not match error with the current Cloud defaults.

Root cause

The ConfluenceCloud client defaults to api_root="wiki/api/v2" and api_version="2". The Confluence v2 REST API requires a different OAuth scope set (read:content:confluence) compared to v1. Standard Atlassian API tokens (issued via id.atlassian.com) are scoped for the v1 REST API and fail against v2 endpoints.

GET https://api.atlassian.com/ex/confluence/<tenant-id>/wiki/api/v2/content
→ 401 Unauthorized; scope does not match

Workaround (currently required)

Pass api_root and api_version explicitly to force v1:

confluence = Confluence(
    url="https://api.atlassian.com/ex/confluence/<tenant-id>",
    username=email,
    password=api_token,
    cloud=True,
    api_root="wiki/rest/api",   # override default wiki/api/v2
    api_version="latest",        # must match api_root
)

This is not discoverable and causes silent failures for new users.

Proposed fix

Auto-detect the appropriate api_root based on the URL when not explicitly set. For api.atlassian.com gateway URLs, fall back to wiki/rest/api (v1) since standard API tokens are issued for v1 scopes. Users with proper v2 OAuth app credentials can still override explicitly.

Alternatively, improve the error message to guide users toward the correct api_root setting when a 401 scope error is detected.

Environment

• Library version: master (post Confluence v2 implementation #1523 new Confluence implementation)
• Confluence Cloud via api.atlassian.com OAuth2 gateway
• Standard Atlassian API token (not an OAuth2 app with custom scopes)

Related

• 401 with scoped access token #1546 — 401 with scoped access token (related but different; that's about PAT scopes)
• [Confluence] Does not use the v2 version of the api-rest #1200 — v2 API support (opposite direction; that's about wanting v2)
• Confluence bug: get_all_pages_from_space only loads first page #1598 / PR [Confluence] Fix pagination for get_all_* methods and unify _get_paged across Cloud/Server #1616 — pagination fix where this was encountered and explicitly left out of scope

[Zircoz]

Closing in favour of #1523. The root cause here is that the library doesn't yet have full v2 OAuth2 support — once #1523 lands, the 401 scope mismatch for \ users will be resolved properly. Adding a workaround or error hint on top of the current code would just be technical debt that #1523 supersedes.