MyJackfruit

Help
Browse topics · Registering an app and getting it approved

Registering an app and getting it approved

← Registering an app and getting it approved

How do I hand over control?

Short answer

Sign in as someone who holds Control on the vault, and send POST /base/authz/grant-vault with the person's vault address and mode control.

Before you start

A sign-in token for someone who holds Control on the vault, and the vault address of the person who is to get it.

Words used here (4)
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
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
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.
Steps
  1. Give the person Control on the vault.

    Send vault, the vault id; grantee, the person's vault address; and mode control, to the vault's own host:
    POST https://<name>.gilb.com/base/authz/grant-vault

    More about this

    The answer is 201 with granted true. From then on the person can give and take away access on this vault, read its access list, take a copy of it, and pass Control on to someone else; on no other vault, and not on the vaults made inside 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. The vault id is the vaultId that GET https://id.gilb.com/lws/vaults gives.

  2. Check the vault's access list.

    Read the list and find the person with control among their levels:
    GET https://<name>.gilb.com/base/consent/vault-acl?vault=<vault id>

    More about this

    The answer on reading a vault's access list by API says more. The owner is on the list with kind owner-inferred: their Control comes from holding the vault, not from a grant, so no one can take it away.

  3. Take Control back when it should end.

    Send the same three fields:
    POST https://<name>.gilb.com/base/authz/revoke-vault

    More about this

    The answer is 200 with revoked true. The person's next grant, revoke or copy on the vault is refused, because GilbPlatform checks Control again on every request. Only someone who holds Control on the vault can take it back.

Deeper

Also asked:

Can I give a whole vault to someone else to own? Not as its owner: no one can change who holds a vault, in GilbApp or from an app. You can give someone Control on it, as the steps show; if you need a vault moved, write to [email protected].

How do I hand control of a vault to someone else by API? Signed in as someone who holds Control there, send vault, grantee, the person's vault address, and mode control to POST /base/authz/grant-vault on the vault's own host.

Only someone who holds Control on a vault can hand it over; holding Read, Write or Append is not enough, and the answer is 403. A computer added to your account with gilb-computer add, a command run on that computer, cannot give Control to a named person: 403.

A holder of Control who does not hold the vault can also share one record, with POST /base/authz/grant-direct. GilbPlatform then keeps the record's stored facts and ignores the facts in the call, so Control cannot change data that way.

To give Control to another vault rather than a person, send POST /base/authz/grant-vault-reach with accessMode control and no accessGrade. That vault then holds Control on this one but reaches nothing in it; sent with an accessGrade, the call is refused with 400.

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).

In GilbApp, Control is one of the four levels under ACCESS in ▸ GRANT ACCESS, offered for a person; the answer on sharing a vault with a person shows it.

Not checked on production: handing over Control this way is from GilbPlatform's code. The Developer Guide, GilbPlatform's guide for people who build apps on it, has no chapter on it yet; its chapter Dev.Guide.Files, https://appbuilder.gilb.com/base/e/06gkzpww3sseh5eskg4h42ts5g, shows that taking a copy needs Control. It can be read with no sign-in, as data for programs and AIs rather than as a web page.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11): src/routes/authz.ts:21-35 (delegable Control: owner or delegated Control capability; Control confers no read or write), :155-174 (grant-vault modes incl. control = delegate Control), :645-700 (requireControlHolder: re-reads on every request; 403 does not hold acl:Control), :1475-1568 (grant-vault: Control gate, computer refusal grant a named person vault access, 201 {vault, grantee, mode, granted}), :1593-1636 (revoke-vault: Revoking a control grant INSTANTLY stops that holder's onward grants, 200 {…, revoked}), :446-530 (C209: Control holder may grant one record; facts from the store, body ignored), :187-214 (control on the vault→vault plane carries no grade), :1675-1718 (grant-vault-reach: Control on accessTo); src/authz/vault-access-edge.ts:918-935 (control-edge-carries-grade → 400); src/authz/entity-acl.ts:138-170 (owner-inferred = not a stored grant; no × on revoke-vault), :190-215 (vault-control: conferring no reach of its own); src/routes/vault.ts:906-951 (export and archive need Control). GilbApp ebd9415e (live at https://gilb.com/app/version.json, read 2026-11-11): src/lib/base/config.ts:700-708 (grant-vault: mode=control delegates Control), src/lib/base/vaultAccess.ts:184-208. Dev.Guide.Files (A 06gkzpww3sseh5eskg4h42ts5g, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) Export (Both need control on that vault, not read). Shared, word for word: the Control sentence (vaults/who-can-give-access-and-to-whom, how-do-i-see-who-can-reach-my-vault); "one of the four levels under ACCESS in ▸ GRANT ACCESS" and offered only for a person (who-can-give-access-and-to-whom); The owner keeps theirs (same page). Row: Developer.DelegateControl. Read 14 November 2026: the live answers Who owns a project when several people work on it? and Can I hand my app over to someone else or sell it?

For developers

curl

give-control.sh

# Hand over Control on a vault to a person.
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":"control"}'
# 201: {"vault":"https://<name>.gilb.com/vault","grantee":"<the person, as GilbPlatform keys them>","mode":"control","granted":true}

curl

take-control-back.sh

# Take Control back.
curl -s https://<name>.gilb.com/base/authz/revoke-vault \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for POST https://<name>.gilb.com/base/authz/revoke-vault>" \
  -H "Content-Type: application/json" \
  -d '{"vault":"https://<name>.gilb.com/vault","grantee":"https://<person>.gilb.com/vault","mode":"control"}'
# 200: {"vault":"https://<name>.gilb.com/vault","grantee":"<the person, as GilbPlatform keys them>","mode":"control","revoked":true}

Checked against GilbApp d529620.