MyJackfruit

Help
Browse topics · Vaults and access by API

Vaults and access by API

← Back to How do I hand over control?

How do I read a vault's access list by API?

Short answer

Send GET /base/consent/vault-acl with the vault id for the whole vault, or GET /base/consent/acl with a record's address for one record.

Before you start

A sign-in token for someone who holds Control on the vault; for one record, the token of the vault's holder.

Words used here (4)
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
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.
GilbPlatform
GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
Steps
  1. Read who has access to the whole vault.

    Send the vault id, URL-encoded, to the vault's own host:
    GET https://<name>.gilb.com/base/consent/vault-acl?vault=<vault id>

    More about this

    The vault id is the vaultId that GET https://id.gilb.com/lws/vaults gives. acl has one entry per person or group: principal; levels, from read, write, append and control; kind, grant, or owner-inferred for the owner; and label, a name where GilbPlatform may show it to you. edges lists the vaults given access to this one, and everyone if it is public, with sourceVault, mode, grade and kind; chainReach lists vaults that reach it only through other vaults. note says what is left out: access given on one record only. Anyone who does not hold Control there gets 404 not found, as for a vault that does not exist.

  2. Read who has access to one record.

    Send the record's address, URL-encoded, to its vault's host:
    GET https://<name>.gilb.com/base/consent/acl?entity=<record address>

    More about this

    Only the vault's holder, the person whose vault it is, can read this list; anyone else, a holder of Control too, gets 404 not found, as for a record that does not exist. GilbPlatform's own code notes that its check of whether the caller holds the vault has answered no for some real holders on the server that keeps people's vaults, and it has not been tested on production for this call, so a 404 here does not prove you are not the holder; step 1 does not use that check. The answer has the same parts, with scope direct: the people and groups given this record on its own, the grants on the whole vault, and the owner.

  3. Read which vaults reach this vault.

    Send the vault id and direction, in for the vaults that reach this one or out for the vaults it reaches:
    GET https://<name>.gilb.com/base/authz/vault-reach-edges?vault=<vault id>&direction=in

    More about this

    The answer has vault, direction and edges. Left out, direction is out. Only someone who holds Control on the vault can ask; anyone else gets 403 here, not 404.

Deeper

A record read as it was at an earlier time, with ?as_of=, and its history, at /history, follow today's access: a record you may no longer read answers 404, the same as a missing one, even for a time when you could read it.

To ask what you yourself may do with one record, send GET /base/access/verdict?entity=<record address>. The answer has read, write and control, each true or false, for the caller only, never for anyone else; with no token all three are false.

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). The two access lists answer 401 to a call with no token or a plain Bearer token.

The full history of every grant, who held what and when, is read only by the account that runs GilbPlatform; an app cannot read it.

In GilbApp the same list is under OTHER PEOPLE AND GROUPS ACCESS RIGHTS; the answer on seeing who can reach your vault shows it.

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 access lists yet.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11): src/routes/consent.ts:1-23 (DPoP hard-bound: 401 no token, 403 suspended, 404 non-disclosure), :68-101 (GET /base/consent/acl: requirePrincipal, authorizeOwnsTargetVault, 404 {error:not found} for a non-owner or a missing entity), :103-137 (GET /base/consent/vault-acl: authorizeHoldsControl, else 404 {error:not found}); src/authz/entity-acl.ts:33-40 (planes: acl, edges incl. public), :69 (levels read|write|append|control), :138-187 (AclEntry: principal, levels, label, webId, kind grant|owner-inferred, labelSource, registered, viewer, aiVault), :190-215 (edges: sourceVault, mode, grade, kind vault-reach|public|vault-control), :248-276 (DirectEntityAcl scope direct, note, acl, edges, chainReach, unclassifiedRows), :456-482 (DirectVaultAcl scope pod; VAULT_ACL_NOTE Does NOT include per-record grants); src/routes/authz.ts:1829-1842 (vault-reach-edges: requireControlHolder → 403; direction in|out, default out; {vault, direction, edges}), :1849-1861 (vault-grants history: requireOwner, deployment owner only); src/routes/access.ts:1-80; src/routes/read.ts:24-31, :250-265, :478-510 (authorization is current-state, never ?as_of; /history the same; identical 404). GilbApp ebd9415e (live at https://gilb.com/app/version.json, read 2026-11-11): src/lib/base/config.ts:688-701 (vault-acl and acl asked of the vault's own origin), src/lib/base/vaultAccess.ts:150-170 (404 = no Control). Shared with everyday/how-do-i-see-a-record-as-it-was-before-its-history (The history follows your access now …), vaults/how-do-i-see-who-can-reach-my-vault (OTHER PEOPLE AND GROUPS ACCESS RIGHTS; an app can ask what you yourself may do), vaults/why-does-a-vault-i-cannot-reach-look-like-it-is-not-there (list shown only to Control holders).: src/routes/consent.ts:68-101 (the per-record list is gated on authorizeOwnsTargetVault), src/auth/vault-owner.ts (D-F8a: the narrow owner predicate answered false for 36 of 50 vault deeds on a user node, 2026-09-05) and the C209 note in src/routes/authz.ts; not re-measured on production. Rows: Developer.ReadAccessListByApi, Security.OldViewsStillObeyCurrentAccess.

For developers

curl

vault-acl.sh

# Who has access to the whole vault? Needs Control on it.
curl -s "https://<name>.gilb.com/base/consent/vault-acl?vault=https%3A%2F%2F<name>.gilb.com%2Fvault" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for GET https://<name>.gilb.com/base/consent/vault-acl>"
# 200: {"vault":"https://<name>.gilb.com/vault","scope":"pod","note":"...","acl":[...],"edges":[...],"chainReach":[...],"unclassifiedRows":0}
# 404: {"error":"not found"}

curl

record-acl.sh

# Who has access to one record? Only the vault's holder may ask.
curl -s "https://<name>.gilb.com/base/consent/acl?entity=<URL-encoded record address>" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for GET https://<name>.gilb.com/base/consent/acl>"

Checked against GilbApp d529620.