Attachments not downloaded when using scoped API token (401 Unauthorized)

[sh1bby]

Description

When running the exporter against Confluence Cloud using a scoped API token (Basic Auth), attachments are not downloaded.

The export itself works, but all attachments are skipped with warnings like:

WARNING There is no attachment with title 'image-xxxx.png'. Skipping export.

In the debug output, the underlying request to download the attachment fails with:

401 Unauthorized
{"code":401,"message":"Unauthorized; scope does not match"}

Steps to reproduce:

1. Configure the exporter to use a Confluence Cloud API token (email + API token)
2. Run an export on a page containing attachments/images
3. Observe that attachments are not downloaded

Confluence token configuration:
I used the following scopes:

Manage
manage:confluence-configuration

Read
read:account
read:confluence-content.all
read:confluence-content.permission
read:confluence-content.summary
read:confluence-groups
read:confluence-props
read:confluence-space.summary
read:confluence-user
read:me
readonly:content.attachment:confluence
read:attachment:confluence
read:embed:confluence

Readonly
readonly:content.attachment:confluence

Search
search:confluence

Expected behavior:
Attachments (e.g. images) should be downloaded as part of the export.

Actual behavior:

• Attachments are skipped
• 401 errors occur when attempting to download them

Environment:

• Confluence Cloud
• Authentication: API token (Basic Auth)
• Installation: via uvx

Diagnostic info

## Bug Report Diagnostic Info

### Version
confluence-markdown-exporter 4.1.1

### System
Python: 3.14.4 (main, Apr 11 2026, 09:31:02) [GCC 15.2.1 20260209]
Platform: Linux-7.0.2-2-cachyos-x86_64-with-glibc2.43
Architecture: x86_64

### Config
Config file: [redacted]

auth:
  confluence:
    https://******.atlassian.net:
      api_token: '[redacted]'
      cloud_id: '[redacted]'
      pat: ''
      username: '[redacted]'
  jira:
    https://******.atlassian.net:
      api_token: '[redacted]'
      cloud_id: '[redacted]'
      pat: ''
      username: '[redacted]'
connection_config:
  backoff_and_retry: true
  backoff_factor: 2
  max_backoff_retries: 5
  max_backoff_seconds: 60
  max_workers: 20
  retry_status_codes:
  - 413
  - 429
  - 502
  - 503
  - 504
  timeout: 30
  use_v2_api: true
  verify_ssl: true
export:
  attachment_export_all: true
  attachment_href: relative
  attachment_path: '{space_name}/attachments/{attachment_file_id}{attachment_extension}'
  cleanup_stale: true
  enable_jira_enrichment: true
  existence_check_batch_size: 250
  filename_encoding: '"<":"_",">":"_",":":"_","\"":"_","/":"_","\\":"_","|":"_","?":"_","*":"_","\u0000":"_","[":"_","]":"_","''":"_","’":"_","´":"_","`":"_"'
  filename_length: 255
  filename_lowercase: false
  include_document_title: false
  lockfile_name: confluence-lock.json
  log_level: DEBUG
  output_path: '[redacted]'
  page_breadcrumbs: false
  page_href: relative
  page_path: '{space_name}/{homepage_title}/{ancestor_titles}/{page_title}.md'
  page_properties_as_front_matter: true
  skip_unchanged: false

Version

confluence-markdown-exporter 4.1.1

Confluence Version

Confluence Cloud

Jira Version

No response

[sh1bby]

FYI: I just found out that it works if I am using an unscoped API token. As far as I can tell from a couple of experiments, as soon as I am using a scoped API token (e.g. with the configuration laid out in the README), the above error appears on my end.

[Spenhouet]

This sounds like you are using a scoped API token which does not allow for attachment loading.

Did you see the README section on scoped tokens? If yes, maybe a scope is missing.

[Cussed5Skies]

I granted a scoped token all 47 read/read-only/search permissions possible in Confluence, which still failed.

DEBUG   HTTP: GET                                                                                                rest_client.py:444
        https://api.atlassian.com/ex/confluence/REDACTED/download/attachments/REDACTED/mermaid-diagram-0-ec5d1ada.png?version=1&modificationDate=1779887610343&cacheVersion=1&api=v2 ->
        401 Unauthorized
DEBUG   HTTP: Response text -> {"code":401,"message":"Unauthorized; scope does not match"}                       rest_client.py:445
WARNING There is no attachment with title 'mermaid-diagram-0-ec5d1ada.png'. Skipping export.                      confluence.py:788

When testing with non-scoped api token, attachments are downloading without problems, PoLP issues aside.

[amagiek]

Same issue here. With a scoped API token (with scopes described in the doc), I can't download attachments. With a non-scoped API token, I can download them.