Skip to content

Commit 71423fb

Browse files
MariusStorhaugMariusStorhaug
committed
📖 [Docs]: Record configured token scopes and candidate commands in SCOPES.md
Updates SCOPES.md to the 48 granular scopes currently configured (25 read, 14 write, 9 delete), grouped by verb. Keeps the current-command mapping, flags that read:blogpost:confluence is no longer configured (Get-ConfluenceBlogPost would 403), and adds an "Additional scopes available for new commands" table listing candidate cmdlets the extra scopes unlock (custom content, databases, groups, users, restriction writes, analytics, comment updates, permission checks, configuration, space settings, embeds, whiteboard delete).
1 parent 59542da commit 71423fb

1 file changed

Lines changed: 98 additions & 25 deletions

File tree

‎SCOPES.md‎

Lines changed: 98 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -5,47 +5,87 @@ prefix) used as HTTP Basic authentication (`<service-account-email>:<token>`)
55
against the API-gateway host `https://api.atlassian.com/ex/confluence/<cloudId>`.
66

77
When you create the token for the service account, select **granular** Confluence
8-
scopes (not the classic `*-confluence-*` scopes). The list below is the full set
9-
the module's commands use today — use it when generating or rotating a token.
8+
scopes (not the classic `*-confluence-*` scopes). Use this document when
9+
generating or rotating a token.
1010

11-
## Scope list
11+
## Configured scopes
12+
13+
The token is currently configured with **48** granular Confluence scopes
14+
(**25 read**, **14 write**, **9 delete**). This is broader than the set the
15+
module's commands use today (see the tables below), leaving headroom for new
16+
commands.
17+
18+
### Read (25)
1219

1320
```text
14-
read:space:confluence
15-
read:space.permission:confluence
16-
read:space.property:confluence
17-
read:page:confluence
18-
read:blogpost:confluence
19-
read:folder:confluence
21+
read:analytics.content:confluence
2022
read:attachment:confluence
2123
read:comment:confluence
22-
read:label:confluence
24+
read:configuration:confluence
25+
read:content:confluence
26+
read:content-details:confluence
27+
read:content.metadata:confluence
28+
read:content.permission:confluence
2329
read:content.property:confluence
30+
read:content.restriction:confluence
31+
read:custom-content:confluence
32+
read:database:confluence
33+
read:email-address:confluence
34+
read:folder:confluence
35+
read:group:confluence
2436
read:hierarchical-content:confluence
25-
read:content-details:confluence
26-
write:page:confluence
27-
write:folder:confluence
37+
read:label:confluence
38+
read:page:confluence
39+
read:permission:confluence
40+
read:space:confluence
41+
read:space-details:confluence
42+
read:space.permission:confluence
43+
read:space.property:confluence
44+
read:space.setting:confluence
45+
read:user:confluence
46+
```
47+
48+
### Write (14)
49+
50+
```text
2851
write:attachment:confluence
52+
write:audit-log:confluence
2953
write:comment:confluence
30-
write:label:confluence
54+
write:configuration:confluence
55+
write:content:confluence
3156
write:content.property:confluence
32-
delete:page:confluence
33-
delete:folder:confluence
57+
write:content.restriction:confluence
58+
write:custom-content:confluence
59+
write:database:confluence
60+
write:embed:confluence
61+
write:folder:confluence
62+
write:group:confluence
63+
write:label:confluence
64+
write:page:confluence
65+
```
66+
67+
### Delete (9)
68+
69+
```text
3470
delete:attachment:confluence
3571
delete:comment:confluence
72+
delete:content:confluence
73+
delete:custom-content:confluence
74+
delete:database:confluence
75+
delete:embed:confluence
76+
delete:folder:confluence
77+
delete:page:confluence
78+
delete:whiteboard:confluence
3679
```
3780

38-
That is 22 scopes: 12 read, 6 write, 4 delete.
39-
40-
## What each scope is for
81+
## Scopes used by the current commands
4182

4283
| Scope | Used by |
4384
| --- | --- |
4485
| `read:space:confluence` | `Get-ConfluenceSpace`, `Get-ConfluenceSiteInfo` |
4586
| `read:space.permission:confluence` | `Get-ConfluenceSpacePermission` |
4687
| `read:space.property:confluence` | `Get-ConfluenceSpaceProperty` |
4788
| `read:page:confluence` | `Get-ConfluencePage`, `Get-ConfluencePageChild`, `Get-ConfluencePageVersion`, `Set-ConfluencePage` (reads before updating) |
48-
| `read:blogpost:confluence` | `Get-ConfluenceBlogPost` |
4989
| `read:folder:confluence` | `Get-ConfluenceFolder` |
5090
| `read:attachment:confluence` | `Get-ConfluenceAttachment` |
5191
| `read:comment:confluence` | `Get-ConfluenceComment` |
@@ -64,17 +104,50 @@ That is 22 scopes: 12 read, 6 write, 4 delete.
64104
| `delete:attachment:confluence` | `Remove-ConfluenceAttachment` |
65105
| `delete:comment:confluence` | `Remove-ConfluenceComment` |
66106

107+
> Important: `Get-ConfluenceBlogPost` needs `read:blogpost:confluence`, which is
108+
> **not** in the configured set. Add that scope (or retire the command) — the
109+
> `/blogposts` endpoints will otherwise return 403. There is also no
110+
> `write:blogpost` / `delete:blogpost`, so blog posts cannot be created or removed.
111+
112+
## Additional scopes available for new commands
113+
114+
These scopes are configured but not yet backed by a command. Each row lists the
115+
candidate cmdlets it would enable (verbs in `{}` share one scope family):
116+
117+
| Scope(s) | Candidate commands |
118+
| --- | --- |
119+
| `{read,write,delete}:custom-content:confluence` | Full custom-content CRUD: `Get-`, `New-`, `Set-`, `Remove-ConfluenceCustomContent` |
120+
| `{read,write,delete}:database:confluence` | Database CRUD: `Get-`, `New-`, `Set-`, `Remove-ConfluenceDatabase` |
121+
| `read:group:confluence` + `write:group:confluence` | `Get-ConfluenceGroup`, `Get-ConfluenceGroupMember`, `New-ConfluenceGroup`, `Add-`/`Remove-ConfluenceGroupMember` |
122+
| `read:user:confluence` + `read:email-address:confluence` | `Get-ConfluenceUser` (by accountId, incl. email); simplifies `Get-ConfluenceCurrentUser` |
123+
| `{read,write}:content.restriction:confluence` | `Add-`, `Set-`, `Remove-ConfluenceRestriction` (complements the existing `Get-ConfluenceRestriction`) |
124+
| `read:analytics.content:confluence` | `Get-ConfluenceContentAnalytics` (page/blog view + viewer counts) |
125+
| `write:comment:confluence` | `Set-ConfluenceComment` (update an existing comment) |
126+
| `read:permission:confluence` + `read:content.permission:confluence` | `Test-ConfluenceContentPermission` / `Get-ConfluenceOperationCheck` |
127+
| `{read,write}:configuration:confluence` | `Get-`/`Set-ConfluenceConfiguration` (look-and-feel / system settings; needs admin) |
128+
| `read:space.setting:confluence` + `read:space-details:confluence` | `Get-ConfluenceSpaceSetting`; richer `Get-ConfluenceSpace` details |
129+
| `{read,write,delete}:content:confluence`, `read:content.metadata:confluence` | Generic/classic content search & operations, e.g. `Find-ConfluenceContent` (CQL) |
130+
| `{write,delete}:embed:confluence` | `New-`/`Remove-ConfluenceEmbed` (Smart Links) — no `read:embed`, so read-back is unavailable |
131+
| `delete:whiteboard:confluence` | `Remove-ConfluenceWhiteboard` only — no `read:`/`write:whiteboard`, so create/read is unavailable |
132+
| `write:audit-log:confluence` | Audit-log export/write (admin) — no `read:audit-log`, so reading records is unavailable |
133+
67134
## Notes
68135

69136
- Scopes are only an **API ceiling**. Effective access is still bounded by the
70137
service account's Confluence **permissions** (global and per-space), so grant it
71-
the matching permissions on the spaces you target.
72-
- This set contains **no space-administration** scope: the token can read space
73-
permissions and properties but cannot change space settings or permissions.
138+
the matching permissions on the spaces you target. Admin APIs (`configuration`,
139+
`audit-log`, `group`) additionally need org/site admin rights.
140+
- **Asymmetric sets** worth noting: `whiteboard` is delete-only; `embed` has
141+
write/delete but no read; `audit-log` is write-only. Commands for those can only
142+
cover the granted verbs.
143+
- This set has **no space-administration write** scope (`write:space` /
144+
`delete:space`): the token can read space settings, permissions and properties
145+
but cannot create, update or delete spaces.
74146
- A few commands reach v1 endpoints that Atlassian maps to these granular scopes:
75147
label add/remove (`write:label:confluence`), attachment upload
76148
(`write:attachment:confluence` plus `read:content-details:confluence`), page
77149
restriction reads and the current user (`read:content-details:confluence`).
78-
- Atlassian applies a soft cap of roughly 50 scopes per token; this set is well
79-
under it, leaving room to grow.
150+
- Atlassian applies a soft cap of roughly **50 scopes** per token; at **48** this
151+
set is near the cap, so adding the missing read scopes (blogpost, whiteboard,
152+
embed) would leave little room and may require dropping unused ones.
80153
- Reference: [Confluence OAuth 2.0 scopes](https://developer.atlassian.com/cloud/confluence/scopes-for-oauth-2-3LO-and-forge-apps/).

0 commit comments

Comments
 (0)