401 Scope problems with Macro Count example

Forge Forge UI Kit and Custom UI
1

Hi - Forge noob here.
I’m trying to get this example working so I can try to build my own Word Count app:

Alas, I believe I’ve followed the instructions correctly and I’m getting permission errors:

ERROR   01:16:45.002  5a3e9c86-484b-4988-8351-184fb722f0be  Error while getContent with contentId 181240032: 401 Unauthorized
ERROR   01:16:45.016  5a3e9c86-484b-4988-8351-184fb722f0be  Error: Error while getContent with contentId 181240032: 401 Unauthorized

In my manifest.yml I tried what is in the example code:

permissions:
  scopes:
      - 'read:confluence-content.summary'

But I get the same error trying these scopes:
- 'read:confluence-content.all'
- 'read:page:confluence'

The example code uses the v1 endpoint:

    const response = await asUser().requestConfluence(route`/wiki/rest/api/content/${payload.contentId}?expand=body.atlas_doc_format`);

Which, for the life of me, I cannot find in the API docs to check required scopes.

It’s not in the v1 API content section.

Does this mean I should try using the v2 endpoint instead? Are the scopes really incompatible?

Hm… so I dug around in the v1 API docs and found that Search content by CQL has a scope of read:content-details:confluence

I gave that a try and NOPE. Same error.

Can anybody help me find the right scope I need?

Thanks!!

2

So I woke up this morning and thought OH - maybe I need to remove the app access for my account and re-authorize the app for the new scope?

So I went here (Atlassian account) and clicked “Remove access” for my app, and argh, now my tunnel is showing me this 410 Gone error:

ERROR   08:47:13.504  0ec5704b-2a66-40dd-bf22-409e27542417  Error while getContent with contentId 181371750: 410 Gone
ERROR   08:47:13.525  0ec5704b-2a66-40dd-bf22-409e27542417  Error: Error while getContent with contentId 181371750: 410 Gone

Here’s my source:

3

Welp, tried deleting my account’s access for the app (word-count), and I’m getting 401 errors again after trying to trigger it again from the menu.

Here’s the “refreshed” permissions granted per the Connected apps screen:

word-count can perform the following actions:

  • Read all content, including content body (expansions permitted). Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
  • View details regarding content and its associated properties.
  • Read a summary of the content, which is the content without expansions. Note, APIs using this scope may also return data allowed by read:confluence-space.summary. However, this scope is not a substitute for read:confluence-space.summary.
  • View page content.

Again, appreciate any guidance. Thanks!

4

:waving_hand: @DarrylLee1 ,

I didn’t try this yet but you are on the right track here. If the REST API is not documented, most likely it doesn’t support the [OAuth 2.0 scopes] and that’s why the app is failing with a 401.
But then it’s strange that is happens also for the Search content by CQL API.

When this happens, I usually try an uninstall and reinstall the app. Maybe something unexpected happened during the installation and the scopes haven’t been set as expected.

:information_source: In this case though, I think the issue is that this v1 API has been retired at the end of last month: Update to Confluence v1 API Deprecation Timeline - #31 by PeterObara

Here are 2 additional observations from me:

  • v1 vs v2: yes please, try to use the v2 as soon as possible. Most of the v1 APIs have been retired now
  • scopes: you want to use the “Classic RECOMMENDED” scopes when writing Forge apps

Hope this helps! I’ve also reported this to our content design team so :crossed_fingers: there will be an update to the doc soon too.

Cheers,
Caterina

5

OMG, duh, I should’ve tried the v2 API first. Yes, this worked!!

I guess that even though v1 works for non-Forge usage (I could load that endpoint in a browser session), it definitely doesn’t work for Forge.

Aw crap, I messed with the scopes and now something isn’t working.

Ok, so I’m pretty sure these don’t work:
- 'read:confluence-content.all'
- 'read:confluence-content.summary'

And the only one that worked is:
- 'read:page:confluence'

Maybe it’s because I changed the call to this:

    const response = await asUser().requestConfluence(route`/wiki/api/v2/pages/${payload.contentId}?body-format=atlas_doc_format`);
6

The ‘read:page:confluence’ looks correct to me based on the doc:
GET Get pages REST API doc

See the highlighted text from the doc above:

image
image1456×892 81.8 KB

Cheers,
Caterina

7

Hmmm, I was looking at this a little more closely, and…

Was there a time where Forge apps required user interaction to grant this permission:
- 'read:confluence-content.summary'

Because I’m not sure where you’re supposed to see this:

  1. You need to allow your app to access your page data, click “Allow access”. This will take you to another page, click “Allow” there.

This tutorial could definitely use a refresh. :-}

8

Yes, there was a time like that! That’s not needed anymore.

And yes, the tutorial needs a refresh. I’ve asked our content design team to look into that.

Cheers,
Caterina

9

Ah, at various points when I was testing where I uninstalled/reinstalled/redeployed/set up a tunnel/ (I think this was only with the Development version), I DID get prompted to “Allow access”, so I do think that step is still valid. I didn’t figure out how to reproduce it exactly.

10

I also get the allow prompt regularly (june 2025). This happens when I update the manifest, and don’t upgrade the install in the instance.