← Back to Who owns a vault's ownership facts?
How do I grant access by API (person, group, whole vault, public)?
Short answer
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 for someone who holds Control on the vault. Each step below is one kind of grant: use the one you need.
Words used here (9)
- record
- A record is one piece of data with its own address, such as a person, a place, a thing or a note.
- sign-in token
- A sign-in token is the credential GilbPlatform issues when a person signs in; your app presents it, with a proof, on each request.
- record's address
- A record's address is the web address that names one record for good: it never changes and is never given to another record.
- record's type
- A record's type says what kind of thing a record is, such as a note, a task or a person, taken from GilbVeda.
- field
- A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda.
- GilbPlatform
- GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
- AI vault
- An AI vault is a small vault that stands for your AI; your AI reaches only the vaults you grant it.
- GilbApp
- GilbApp is the app, opened in a web browser at https://gilb.com/app, where you open, fill and share your vaults.
- agent
- An agent is your AI following one written procedure, its standing instructions, for one kind of work.
Steps
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://<name>.gilb.com/base/authz/grant-directMore about this
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.
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://<name>.gilb.com/base/authz/grantMore about this
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.
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://<name>.gilb.com/base/authz/grant-vaultMore about this
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. 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.
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://<name>.gilb.com/base/authz/grant-vault-reachMore about this
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.
Make the whole vault public.
Send vault, the vault id, to the vault's own host:
POST https://<name>.gilb.com/base/authz/grant-vault-publicMore about this
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. 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, sharing one record 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
# 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
# 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
# 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}
Checked against GilbApp d529620.