MyJackfruit

Help
Browse topics · For developers

For developers

← Back to Which token should my app use?

How does my app's server read its own vault?

Short answer

Register your app's key, ask for a token and use it, make an AI vault and bind your app, grant it access, then read.

Before you start

A server for your app that can keep a private key secret, and a vault of your own that holds the content, with Control on it.

Words used here (5)
AI vault
An AI vault is a small vault that stands for your AI; your AI reaches only the vaults you grant it.
field
A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda.
GilbApp
GilbApp is the app, opened in a web browser at https://gilb.com/app, where you open, fill and share your vaults.
Client ID
A Client ID is your AI's fixed name on GilbPlatform; find it by pasting GilbApp's line in a new Terminal window, then bind the AI.
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
Steps
  1. Register your app's key.

    On your server, make a new P-256 key pair, keep the private half there, and send the public half, with no sign-in:
    POST https://id.gilb.com/base/client/register

    More about this

    Send JSON with clientPublicKey (the public members only), declaredOrigin and clientDisplayName. The answer holds clientId, the name the platform gave your app when it was registered, and confersAuthority false: registering gives no access. The same key gives the same clientId again. A page in a browser cannot keep the private key secret, so a page alone cannot use this way.

  2. Ask for a token and use it once.

    Ask for a token with a signed assertion and a new DPoP proof, then use it once for any request, such as GET https://id.gilb.com/base/e/first-use, which answers 404. The token request is:
    POST https://id.gilb.com/base/oauth/token

    More about this

    A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449). Send the form fields grant_type client_credentials, client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer, client_assertion, and scope base.read or base.write (base.read if left out; any other answers 400 invalid_scope). The assertion is a short JWT your server signs with the private key: iss and sub your clientId, aud the token address, iat, exp and a new jti; use it once. The token lasts 300 seconds, with no refresh. The platform makes your app's identity the first time the app uses a token, and step 3 needs it.

  3. Make an AI vault in GilbApp.

    Do steps 1 to 3 of the answer on making an AI vault and connecting Claude Code, on a vault of your own that only you can read, and keep the AI vault's address it shows.

    More about this

    An AI vault is a small vault that stands for your app; it holds no content of its own. Its address ends in /vault. If someone else can read or write the vault you make it in, or a vault above it, the mint is refused. A vault cannot be turned into an AI vault later.

  4. Bind your app to the AI vault.

    Do steps 4 and 5 of the same answer, with your app's clientId in place of Claude Code's Client ID. GilbApp then says the client now acts as this vault.

    More about this

    Only you, who made the AI vault, can bind it; the app cannot bind itself, and an app acts as one AI vault for good. client has no machine principal yet means the token of step 2 was never used: use it, then bind again.

  5. Give the AI vault access to the content vault.

    On the vault that holds the content, give the AI vault's address read access, and write access if your app writes, as the answer on giving your AI access to a vault shows.

    More about this

    Under ONWARD REACH, choose Passes up hierarchy: the Developer Guide's check on production used it. With Stops here, the one chosen when the section opens, only the AI vault gets the access, which is what your app acts as; the Guide has not checked that on production. No one can be given access into the AI vault. To end the app's access, take the grant away; its next request is refused.

  6. Read and write from your server on the content vault's host.

    Ask for a new token as in step 2, and send each call to the content vault's own host with a new proof:
    GET https://<content vault>.gilb.com/vault/e/<record-id>

    More about this

    A read answers 200 with the record. To write, the grant needs write and the token scope base.write; a create goes to POST https://<content vault>.gilb.com/lws/vault/<encoded vault address>/c. An app that is not bound or not granted gets 404 on a read, the same as a missing record, and 403 on a write; a base.read token gets 403 on a write too.

Deeper

Also asked:

What is an AI vault, and how does my code use one? An AI vault is a small vault that stands for your app and holds no content of its own. You bind your app's clientId to it and give it access to the content vault; your server's tokens then act as it. Steps 3 to 6 show how.

Your end users get no grant: they use your app, and your app decides what to show them from what it reads. Do not pass the token or the private key to a page or a user. If the key leaks, anyone holding it can act as your app: take the grant away at once, then ask the platform owner, who runs GilbPlatform, to move your registration to a new key and to make it the only key (your clientId stays), or register a new key, which gives a new clientId and needs steps 2 to 5 again with a new AI vault. You cannot move a registration to another key yourself: no call does it. The platform owner can, with a script only the owner runs: it keeps your clientId, and until the owner makes the new key the only one, your server may sign with either. A wrong origin or name is not changed this way; it needs a new key.

Not checked on production yet: listing or searching the content vault as the app, and changing or ending a record as the app. There is no screen in GilbApp to register an app; the registration is a call.

The full reference is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapter Dev.Guide.AppAccess, https://appbuilder.gilb.com/base/e/06gqw6jdn9sgbc9rfbfrwc7rec. It can be read with no sign-in, as data for programs and AIs rather than as a web page.

Source: Dev.Guide.AppAccess (A 06gqw6jdn9sgbc9rfbfrwc7rec, Process, 2026-11-11; read for agreement, not copied): Entry.Owner, Entry.Server, AiVault, Register (confersAuthority false; same key same clientId), FirstToken (fields; assertion claims; scope default base.read; invalid_scope; 300 s; no refresh; first use makes the identity; https://id.gilb.com/base/e/first-use 404), Bind (This client now acts as this vault.; only the maker; a client acts as one vault; refusal table), Grant (Passes onward (full reach) verified; scoped not verified; reach-into-ai-agent-vault), Read (200; 404 for unbound, grant removed), Write (base.write + write grant; 403 cases), EndUsers (no grant; key leak recovery; no GilbApp screen to register); Dev.Guide.Errors Answer34-41. GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11): src/routes/client-registration.ts:90, :108 (confersAuthority false); src/routes/machine-token.ts:164 (POST /base/oauth/token); src/auth/machine-token.ts:259-310 (the proof's embedded key becomes cnf.jkt), :315-330, :363 (invalid_scope); src/routes/authz.ts:1575 (bind-agent-vault), :1683 (grant-vault-reach), :1794 (revoke-vault-reach); src/auth/bind-agent-vault.ts:110, :127 (client has no machine principal yet — it must obtain a token once first.); src/authz/vault-access-edge.ts:1038 (reach-into-ai-agent-vault). GilbApp ebd9415e (live at https://gilb.com/app/version.json, read 2026-11-11): src/components/VaultAccessManager.tsx:385 (This client now acts as this vault.), :188 (edgeGrade starts at scoped, so Stops here is chosen when the section opens), :710-713 (Onward reach), :723-746 (Stops here = scoped, Only the grantee vault gets this access — no inheritance; Passes up hierarchy = full), :894, :925. The example app-token.ts was written from the code and the chapter; not run (needs a registered key). Key rotation: GilbPlatform 498d29a0 scripts/approve-client.ts:15-16, :260-265 (set-next-key <clientId> <public JWK>, promote-next-key <clientId>, run only by the platform owner against the identity store); src/auth/client-registry.ts:613-660 (setClientNextPublicKey: The client id stays the id derived from the first key); src/auth/machine-token.ts:213-217 (an assertion signed by either key is accepted until the next key is promoted, same client id). Registration itself stays create-only (src/auth/client-registry.ts), so a wrong origin or name still needs a new key. Dev.Guide.AppAccess still says A registration cannot be changed to another key. (last paragraph of its Keep-the-key section); the page follows the code, and the Guide needs the same correction. Rows: Developer.AppServerReadsOwnVault, AppAccessRefusals.

For developers

TypeScript

app-token.ts

import { SignJWT, importJWK, type JWK } from "jose";

const TOKEN_URL = "https://id.gilb.com/base/oauth/token";

// clientId from the registration; privateJwk is the app's private P-256 key, kept on the server.
// dpopProof is a new proof for POST TOKEN_URL, made with the key you use for every call with this token.
export async function appToken(clientId: string, privateJwk: JWK, dpopProof: string, scope: "base.read" | "base.write") {
  const key = await importJWK(privateJwk, "ES256");
  const now = Math.floor(Date.now() / 1000);
  const assertion = await new SignJWT({})
    .setProtectedHeader({ alg: "ES256", typ: "JWT" })
    .setIssuer(clientId)
    .setSubject(clientId)
    .setAudience(TOKEN_URL)
    .setIssuedAt(now)
    .setExpirationTime(now + 60)
    .setJti(crypto.randomUUID()) // a new one every time: an assertion works once
    .sign(key);
  const res = await fetch(TOKEN_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded", DPoP: dpopProof },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      client_assertion: assertion,
      scope,
    }),
  });
  if (res.status !== 200) throw new Error(`token call answered ${res.status}`);
  return (await res.json()) as { access_token: string; token_type: "DPoP"; expires_in: number; scope: string };
}

Checked against GilbApp d529620.