# How do grant scopes work \(cascade, type, preview\)?

Checked 2026-11-15 against GilbApp d5296208bbffa2ab70076e6194f5537c4be1ddf7.

Preview the records a grant would reach, then grant a group a record and everything part of it, or only one type of record there.

## Before you start

[A sign-in token](http://support.gilb.com/help/how-do-i-use-the-sign-in-kit) for someone who holds "Control" on the vault the record is in, and the address of a group.

## Steps

1. Preview what a grant on a record would reach.

   Send root, the record's address, and mode, read or write, to the host in the record's address; nothing is written:
   POST https://&lt;name\>.gilb.com/base/authz/grant-scope

   The answer is 200 with entities, the address of every record the grant would reach, count, and projected false. It reaches the record and every record that is part of it, and their parts in turn, at any depth. It never reaches upward: a part that also belongs to another record does not open that other record. Part of means the a:partOf link between records. Leave plane out; a plane GilbPlatform does not know answers 400 with registeredPlanes, the ones it knows.
2. Grant a group the record and everything part of it.

   Send root, the record's address; group, the group's address, which ends in /base/g/ and an id; and mode:
   POST https://&lt;name\>.gilb.com/base/authz/grant-scope-cascade

   The answer is 201 with granted true, entities and count. A record that becomes part of the root later is inside the grant too, and a record taken out of it leaves. POST /base/authz/revoke-scope-cascade with the same fields takes it away. These grants go to a group only, never to one person: a group is several people given access together, not a MyNet group, which is a vault \(MyNet is Gilb's app for your profile and network\); only the platform owner, who runs GilbPlatform, can add a person to a group today.
3. Preview a grant on one type inside a record.

   Send scopeRoot, the record that holds the area; typeRoot, the type; and mode:
   POST https://&lt;name\>.gilb.com/base/authz/grant-type-scope

   It reaches only records that are both part of scopeRoot, at any depth, and of typeRoot or a type under it in GilbVeda, the shared list of terms; for example, every piece of equipment under one site. The answer is 200 with typeClosure, the types it counts, entities, count, and projected false; nothing is written.
4. Grant a group that type inside the record.

   Send scopeRoot, typeRoot, group and mode:
   POST https://&lt;name\>.gilb.com/base/authz/grant-type-scope-cascade

   The answer is 201 with granted true, entities and count. POST /base/authz/revoke-type-scope-cascade with the same fields takes it away. A record of another type under the same root stays closed to the group, and so does a record of that type outside the root.

## Deeper

Also asked:

How do I grant one record and everything under it, or only one type? For the record and every record part of it, send root, group and mode to POST /base/authz/grant-scope-cascade; for one type under it, send scopeRoot, typeRoot, group and mode to POST /base/authz/grant-type-scope-cascade.

Only someone who holds "Control" on the vault the root record is in can preview or grant; anyone else gets 403. "Control" gives no "Read" or "Write" by itself, but whoever holds it can take a copy of the whole vault, every record and file, and can give themselves "Read" or "Write". A computer added to your account with gilb-computer add, a command run on that computer, cannot preview or grant this way: 403. A record in an AI vault, a small vault that stands for an app or an AI, cannot be granted this way: 400.

No grant opens a record whose holder narrowed who may see it, such as a detail in MyNet, Gilb's app for your profile and network, set to "Private". Someone outside that choice is refused, for reading and for writing, even with a grant on the whole vault or one of the grants on this page. Only a grant on that one record that names the person, with grant-direct or grant-write-direct, lets them in; the holder always can.

Every call carries the header Authorization: DPoP followed by the token, and [a new DPoP proof](http://support.gilb.com/help/how-do-i-make-a-dpop-proof-for-each-request). A DPoP proof is a short signed note your app makes for one request, naming its method and address \(RFC 9449\). With no token, or a plain Bearer token, the answer is 401.

GilbPlatform keeps these grants as facts with their history: taking one away ends it from the next request on, and the record of who held it stays.

To give an app's server, signed in as itself, one area at one mode, with an optional end time, someone who holds "Control" sends POST /base/authz/grant-principal-scope with the app as grantee; GilbPlatform's code has it, and this page does not cover it.

To give a whole vault rather than one record and its parts, use POST /base/authz/grant-vault, as [the answer on granting access by API](http://support.gilb.com/help/how-do-i-grant-access-by-api) shows. GilbApp has no screen for the grants on this page.

Not checked on production: these calls are from GilbPlatform's code. The Developer Guide, GilbPlatform's guide for people who build apps on it, has no chapter on them yet.

Source: GilbPlatform 498d29a0 \(live at https://id.gilb.com/version, read 2026-11-11\): src/routes/authz.ts:30-35 \(DPoP-only\), :272-290 \(grant-scope body: root, mode, optional plane and grantee\), :292-306 \(cascade body: root, group, mode\), :355-367 \(type-scope body\), :369-382 \(type-scope cascade body\), :645-700 \(Control gate, 403\), :1881-1926 \(grant-scope: Control gate, AI-vault 400, computer 403, 200 {root, plane, mode, entities, count, projected:false}, 400 {error, registeredPlanes} for an unknown plane\), :1941-1979 \(grant-scope-cascade: 201 {…, granted, entities, count}\), :1985-1999 \(revoke-scope-cascade 200\), :2141-2189 \(grant-type-scope: 200 {…, typeClosure, entities, count, projected:false}\), :2195-2235 \(grant-type-scope-cascade 201\), :2238-2252 \(revoke 200\), :2255-2267 \(type-scope-grants history: deployment owner only\); src/authz/grant-cascade.ts:1-60 \(root plus downward a:partOf descendants; never ascends; GRANTEE = a GROUP; revoke closes in place, history survives\); src/authz/principal-scope-grant.ts:594-660 and src/write/ingest.ts:2440; src/authz/type-grant.ts:1-40 \(scope ∩ a:subTypeOf type membership; four-quadrant confinement\); src/routes/authz.ts:2004-2043 and src/authz/principal-scope-grant.ts:1-15 \(grant-principal-scope: one backend principal signed in with client\_credentials, one area, one mode of read\|write\|append\|create\|change\|delete, optional end; named, not covered\); src/routes/authz.ts:788-800 \(membership: requireOwner, the deployment owner\); src/authz/audience-tier.ts:212-224 \(inside the rung: public, the holder, the circle, signed-in\), :245-339 \(the rung binds every mode; the only exemption is a per-entity a:directReader on a read / a:directWriter on a write naming the requester\), src/authz/predicate.ts:181-214 \(restrictive AND over every grant arm\). GilbVeda \(public read https://veda.gilb.com/base/terms?q=, 2026-11-11\): t/ScopeReaderGrant, t/ScopeWriterGrant, t/TypeScopeReaderGrant, t/VisibilityTier \("who may discover it"\) — all Suggested.: src/routes/authz.ts:2000-2038 \(grant-principal-scope: requireControlHolder, grantee names the app's principal, a computer key 403, a record in an AI vault 400\).: src/baseconnect/org-join.ts:351 \(a MyNet group is a vault\), src/routes/authz.ts:789-799 \(membership: requireOwner\). Rows: Developer.GrantScopeCascade, GrantTypeScope, PreviewScopeGrant, Security.PrivateTierDeniesAmbientGrants.

## For developers

### curl: preview-scope.sh

```curl
# What would a read grant on this record and its parts reach? Writes nothing.
curl -s https://<name>.gilb.com/base/authz/grant-scope \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for POST https://<name>.gilb.com/base/authz/grant-scope>" \
  -H "Content-Type: application/json" \
  -d '{"root":"<record address>","mode":"read"}'
# 200: {"root":"<record address>","plane":"a:partOf","mode":"read","entities":[...],"count":<n>,"projected":false}
```

### curl: grant-scope.sh

```curl
# Give a group read on the record and everything part of it.
curl -s https://<name>.gilb.com/base/authz/grant-scope-cascade \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for POST https://<name>.gilb.com/base/authz/grant-scope-cascade>" \
  -H "Content-Type: application/json" \
  -d '{"root":"<record address>","group":"<group address>","mode":"read"}'
# 201: {"root":"<record address>","group":"<group address>","mode":"read","plane":"a:partOf","granted":true,"entities":[...],"count":<n>}
```
