# How do I grant access by API \(person, group, whole vault, public\)?

Checked 2026-11-15 against GilbApp d5296208bbffa2ab70076e6194f5537c4be1ddf7.

With the token of someone who holds "Control" on the vault, send the grant call for one record, the whole vault, another vault, or everyone.

## 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. Each step below is one kind of grant: use the one you need.

## Steps

1. Share one record with a person or with everyone.

   Send entity, the record's address; principal, the person's vault address; and type and facts, the record's type and every fact it holds now, to the host in the record's address:
   POST https://&lt;name\>.gilb.com/base/authz/grant-direct

   To let them change it too, send the same to /base/authz/grant-write-direct; it gives read as well. Sent by the vault's holder, the call writes the whole record again from facts: a fact you leave out is removed, and so is a change made after you read it. Read it just before, each fact under the name the vault stores it by \(starting with a:\). Steps 2 and 3 have no such risk. Sent by a holder of "Control" who does not hold the vault, it keeps the stored facts and ignores facts. For everyone, read only, principal is https://veda.gilb.com/base/t/PublicGrantee. The answer is 201, or 200 when nothing changed, with granted true. POST /base/authz/revoke-direct with entity and principal takes the person's read and write of the record away.
2. Give a group one record.

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

   That gives the group read; /base/authz/grant-write gives write, and read with it. /base/authz/revoke-group and /base/authz/revoke-write-group, with the same two fields, take read or write away; taking write away leaves read. 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, so ask the platform owner for the group first. The answer is 201 with granted true.
3. Give a person or a group the whole vault.

   Send vault, the vault id; grantee, the person's vault address or a group's address; and mode, which is read, write, append or control, to the vault's own host:
   POST https://&lt;name\>.gilb.com/base/authz/grant-vault

   The vault id is the vaultId that GET https://id.gilb.com/lws/vaults gives; use it as given. write gives read as well; append lets them add to the vault only, not read or change what is there; control is in [the answer on handing over control](http://support.gilb.com/help/how-do-i-hand-over-control). read and write also reach the vaults made inside this one, except an AI vault, a small vault that stands for an app or an AI; append and control stay on this vault. The answer is 201 with granted true. POST /base/authz/revoke-vault with the same three fields takes one mode away. Everyone cannot be the grantee here: the answer is 400 and points to step 5.
4. Let another vault reach this vault.

   Send vaultGrantee, the vault that gets access; accessTo, this vault; accessMode, read or write; and accessGrade, full or scoped:
   POST https://&lt;name\>.gilb.com/base/authz/grant-vault-reach

   Use it for an AI vault or for any other vault. With full the grantee vault also reaches the vaults this vault was itself given access to; with scoped it reaches only this vault, which GilbApp calls "Stops here". Only someone who holds "Control" on accessTo can send it; holding the other vault gives nothing. The answer is 201 with granted true, or 200 when it was there already. POST /base/authz/revoke-vault-reach with the first three fields takes it away. No one can be given access into an AI vault: 400 "reach-into-ai-agent-vault".
5. Make the whole vault public.

   Send vault, the vault id, to the vault's own host:
   POST https://&lt;name\>.gilb.com/base/authz/grant-vault-public

   From then on anyone, signed in or not, can read the vault, except a record whose holder narrowed who may see it, such as a MyNet detail set to "Private"; no one can be given writing this way. The answer is 201 with public true, or 200 when it was public already. POST /base/authz/revoke-vault-public with vault makes it private again; a record made public on its own, with step 1, stays public. Vaults made inside a public vault are not made public with it.

## Deeper

Also asked:

How do I take access away again by API? Send the matching revoke call: /base/authz/revoke-direct for a person on one record, revoke-group and revoke-write-group for a group, revoke-vault for one mode on a vault, revoke-vault-reach for another vault, revoke-vault-public for a public vault; each step names its fields.

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\). A plain Bearer token is refused with 401, and a call with no token answers 401 "This surface requires an authenticated caller \(no token presented\)".

Only someone who holds "Control" on a vault can give access there; whoever makes a vault holds it. "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". Holding "Read", "Write" or "Append" lets you give access to no one: the answer is 403, and on most grant calls its message says the caller "does not hold acl:Control".

GilbPlatform takes four kinds of receiver and no others: a person, a group \(several people given access together\), another vault, and, for reading only, everyone. Anything else is refused with 400, not stored.

A computer added to your account with gilb-computer add, a command run on that computer, can make things public or private and take access away, but cannot give access to a named person, group or vault; GilbPlatform answers that this is done in GilbApp.

A refusal gives its reason in error and message. Two grants on the same record at the same moment can answer 409: nothing was changed, so send it again. A grant works from the next request on, and so does taking it away; GilbPlatform keeps the old grant in its history.

GilbApp makes the same grants on screen: the answers on [sharing a vault with a person](http://support.gilb.com/help/how-do-i-share-a-vault-with-a-person), [sharing one record](http://support.gilb.com/help/how-do-i-share-one-record-not-the-whole-vault) and making a vault public show how.

The Developer Guide, GilbPlatform's guide for people who build apps on it, checked three refusals on production: no token \(401\), a grant to a named person with a computer key \(403\), and a grant by someone who neither holds the vault nor holds "Control" \(403\). It has no chapter on grants yet; its chapters Dev.Guide.AppAccess, https://appbuilder.gilb.com/base/e/06gqw6jdn9sgbc9rfbfrwc7rec, and Dev.Guide.Errors, https://appbuilder.gilb.com/base/e/06gkzpwxmnxf90zcc3mzc757xg, show a vault given access to another vault and the refusals. It can be read with no sign-in, as data for programs and AIs rather than as a web page. The other calls here are from GilbPlatform's code.

Source: GilbPlatform 498d29a0 \(live at https://id.gilb.com/version, read 2026-11-11\): src/routes/authz.ts:30-35 \(DPoP-only on all grant routes; a plain Bearer → 401\), :148-153 \(grant body\), :161-174 \(grant-vault body; modes\), :204-214 \(grant-vault-reach body; control without grade\), :234-242 \(public: read only\), :405-418 \(grant-direct body\), :483-510 \(grant-direct authority: holder or Control; 403 "neither holds the vault of … nor holds acl:Control", line 493\), :518-530 \(Control holder: stored facts, body ignored\), :645-700 \(requireControlHolder: 401 no/bad DPoP token, 403 "does not hold acl:Control", line 696\), :737-750 \(409 ConcurrentWrite\), :806-827 \(POST /base/authz/grant: group read, 201\), :850-864 \(revoke-group\), :903-1145 \(grant-direct: resolve grantee, PublicGrantee read only, 201/200, granted\), :1150-1213 \(revoke-direct, 200, revoked\), :1233-1256 \(grant-write: write and read\), :1262-1276 \(revoke-write-group: write only\), :1284-1458 \(grant-write-direct; read planted too\), :1475-1568 \(grant-vault: crossing to the vault's node, Control gate, computer refusal, PublicGrantee 400 "A vault is made public with POST /base/authz/grant-vault-public …", write also grants read at :1556, 201 granted\), :1599-1636 \(revoke-vault 200 revoked\), :1675-1718 \(grant-vault-reach: Control on accessTo; 201/200; 400 on VaultAccessEdgeRefusedError\), :1729-1778 \(grant-vault-public / revoke-vault-public: 201/200, public true/false\), :1791-1821 \(revoke-vault-reach\); src/auth/app-standing.ts:231-245 \(computer: "a computer may publish, unpublish and revoke access, but may not …; do this in GilbApp"\); src/authz/direct-grantee.ts:600-685, :626-633 \(directGrantFacts: grant plane from the store; "A grant call whose body OMITS the item's ordinary facts still retracts them", R-C161-GRANTFACTSERASE; write grant adds read\); src/authz/grantee-uri.ts:52-66, :145-151 \(/vault or /base; 400 refusal for any other grantee\); src/authz/vocab.ts:125 \(read, write, append, control\); src/authz/vault-access-edge.ts:528-537, :884-935, :1031-1041 \(reason codes incl. reach-into-ai-agent-vault, control-edge-carries-grade, data-edge-without-grade\); src/authz/predicate.ts:73 \(t/PublicGrantee\). GilbApp ebd9415e \(live at https://gilb.com/app/version.json, read 2026-11-11\): src/lib/base/config.ts:708 \(grant-vault to the vault's origin\), :783-788 \(public\), :858-879 \(vault reach to accessTo's origin\), :53-70 \(vaultOriginOf\); src/lib/base/vaultAccess.ts:184-208 \(body {vault, grantee, mode}\); src/lib/base/entityShare.ts:40-86 \(per-record grant asked of the record's own vault host\); src/components/VaultAccessManager.tsx:723-746 \("Stops here" = scoped, "Passes up hierarchy" = full\). Dev.Guide.AppAccess \(A 06gqw6jdn9sgbc9rfbfrwc7rec, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied\) Grant \(grant-vault-reach body and answer; revoke-vault-reach; reach-into-ai-agent-vault\); Dev.Guide.Errors \(A 06gkzpwxmnxf90zcc3mzc757xg, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied\) Answer13, Answer20, Answer21 \(verified 2026-10-15\), Answer39. src/authz/direct-grantee.ts:626-633 \(a grant body that omits facts retracts them, R-C161-GRANTFACTSERASE\), src/routes/authz.ts:1040-1081 \(the holder's state is built from the body and written as a full-state ingest; no expected state is sent\), GilbApp ebd9415e src/lib/base/entityShare.ts:11 \("Facts MUST be a:-prefixed on the wire for full-state ingest"\); the 403 sentence left step 1 \(Deeper already says only a "Control" holder can give access\).: src/baseconnect/org-join.ts:351 \(a MyNet group is a vault members get "Read" on\), src/routes/authz.ts:789-799 \(membership: requireOwner, the platform owner\); MyNet gloss and the people pages.: src/authz/audience-tier.ts:245-339 \(a record's narrowed audience binds ambient reach, the public grant included; only a per-record a:directReader or a:directWriter naming the person passes\). Rows: Developer.GrantPersonAccess, GrantGroupAccess, GrantWholeVault, GrantVaultPublicRead, GrantVaultReachByApi.

## For developers

### curl: grant-vault.sh

```curl
# Give a person read on a whole vault. The token is of someone who holds Control on it.
curl -s https://<name>.gilb.com/base/authz/grant-vault \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for POST https://<name>.gilb.com/base/authz/grant-vault>" \
  -H "Content-Type: application/json" \
  -d '{"vault":"https://<name>.gilb.com/vault","grantee":"https://<person>.gilb.com/vault","mode":"read"}'
# 201: {"vault":"https://<name>.gilb.com/vault","grantee":"<the person, as GilbPlatform keys them>","mode":"read","granted":true}
```

### curl: make-public.sh

```curl
# Let anyone read the whole vault. Read only.
curl -s https://<name>.gilb.com/base/authz/grant-vault-public \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for POST https://<name>.gilb.com/base/authz/grant-vault-public>" \
  -H "Content-Type: application/json" \
  -d '{"vault":"https://<name>.gilb.com/vault"}'
# 201: {"vault":"https://<name>.gilb.com/vault","mode":"read","entity":"<grant id>","changed":true,"public":true}
```

### curl: vault-reach.sh

```curl
# Let another vault read this one, and stop there (scoped).
curl -s https://<name>.gilb.com/base/authz/grant-vault-reach \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for POST https://<name>.gilb.com/base/authz/grant-vault-reach>" \
  -H "Content-Type: application/json" \
  -d '{"vaultGrantee":"https://<other>.gilb.com/vault","accessTo":"https://<name>.gilb.com/vault","accessMode":"read","accessGrade":"scoped"}'
# 201: {..., "entity":"<grant id>","changed":true,"granted":true}
```
