Skip to content

Commit 0b6f02d

Browse files
committed
docs(permissions): document the delegable-scope read surface on the delegated-administration page
The page described what the write gate enforces but had no answer to 'what may I delegate?' — the question an admin surface must ask to narrow its pickers. Adds the endpoint, the SDK call, the response shape, and the three properties that matter: it narrows but does not decide, a position appears only if every set it distributes is allowlisted, and it is strictly self-scoped. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015FebXPaaGrLhGKw1LHPbpL
1 parent 04bd900 commit 0b6f02d

1 file changed

Lines changed: 44 additions & 0 deletions

File tree

content/docs/permissions/delegated-administration.mdx

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,50 @@ The [explain engine](/docs/permissions/explain) closes the loop twice:
9292
- contributor attribution plus the `granted_by` stamp answer both *who
9393
granted this* and *who could have*.
9494

95+
## Reading your own scope
96+
97+
The gate also answers the *read* question — **what may I delegate?** — so an
98+
admin surface can narrow its pickers instead of offering the whole tree and
99+
letting the user discover the boundary by being refused:
100+
101+
```bash
102+
GET /api/v1/security/my-delegable-scope
103+
```
104+
105+
```ts
106+
const scope = await client.security.describeDelegableScope();
107+
```
108+
109+
```jsonc
110+
{
111+
"isTenantAdmin": false,
112+
"placeableBusinessUnitIds": ["bu_east", "bu_east_sales"], // where you may place people
113+
"assignablePositions": ["sales_rep"], // positions you may hand out
114+
"scopes": [ // the scopes those derive from
115+
{ "setName": "sub_admin", "businessUnit": "east", "manageAssignments": true,
116+
"assignablePermissionSets": ["sales_user"], "businessUnitIds": ["bu_east", "bu_east_sales"] }
117+
]
118+
}
119+
```
120+
121+
Three properties worth knowing:
122+
123+
- **It narrows; it does not decide.** The lists are computed by the same
124+
helpers the write gate enforces with, so an option here is one the gate
125+
accepts — but the gate still runs on the write. A UI that skipped it would
126+
be refused, not obeyed.
127+
- **A position appears only if you may hand out *every* set it distributes.**
128+
`mixed_pos` bundling an allowlisted set with a non-allowlisted one is
129+
withheld, exactly as the write gate would refuse it.
130+
- **Strictly self-scoped** — there is no target-user parameter, so it
131+
discloses nothing beyond the authority you already hold. A tenant-level
132+
admin comes back `isTenantAdmin: true` with everything enumerated, so
133+
consumers render one uniform picker rather than special-casing.
134+
135+
Scoped invitations (ADR-0105 D8) are the first consumer: the invitation form
136+
narrows its unit/position pickers with this, and the invitation's placement
137+
intent is then authorized against the *issuer's* scope at issuance time.
138+
95139
## See also
96140

97141
- [Permission Sets](/docs/permissions/permission-sets) — the container `adminScope` rides on

0 commit comments

Comments
 (0)