MyJackfruit

Help
Browse topics · For developers

For developers

← For developers

How do I read an organisation's card?

Short answer

Find the organisation's vault id, ask GET https://id.gilb.com/base/connect/org-card?vault=<vault id, encoded>, and show each field in the answer.

Before you start

No account is needed for what an organisation shares with everyone; for more, your app holds a signed-in person's token.

Words used here (4)
field
A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda.
online card
An online card is the card a person keeps about themselves on GilbPlatform; others see only what the person shares with them.
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
sharing level
A sharing level says who may see one thing you share in MyNet, from Public, for everyone, to Private, for you alone.
Steps
  1. Find the organisation's vault id.

    From a card in the person's own vault that is connected to the organisation's online card, ask with the person's token:
    GET https://id.gilb.com/base/connect/online-card-anchor?record=<the card's address, encoded>

    More about this

    An organisation's online card is the card it keeps about itself, as a person keeps theirs. For an organisation the answer has vaultId, the address of its vault (the store that holds its data, such as https://<host>/base), and vaultRepresents https://veda.gilb.com/base/t/Organization; for a person, vaultId is null and principal names them. The card must be in the caller's own vault and linked by a:sameAs; anything else answers 404 no_online_card, and no token 401 Sign in required. To find an organisation by name instead, GET https://id.gilb.com/base/connect/org-find?q=<words>, with a token and a new DPoP proof, gives each listed group with its vaultId. Encoded means written with encodeURIComponent, so the address fits in one part of the path.

  2. Ask for the card.

    Send the vault id, encoded, with the person's token if you have one, or with none:
    GET https://id.gilb.com/base/connect/org-card?vault=<vault id, encoded>

    More about this

    With no token you get the fields the organisation shares with everyone and nothing else. With a token you also get the fields shared with that person, and someone who holds Control on the organisation's vault, the right to manage who else has access to it, gets every field it has placed. The token goes in Authorization: DPoP with a new DPoP proof (a short signed note your app makes for one request, naming its method and address, RFC 9449), or as a plain Bearer token: /lws, /files and many /base routes, such as /base/search, take it with no proof; the routes that sign in, trade tokens, register an app or run the AI chat do not.

  3. Show each field in the answer.

    Show each entry in fields, and about when it is not null:
    {surface:connect-org-card/1,vault:<vault id>,fields:[...],about:null,complete:true}

    More about this

    Each field has field, the fact name, such as a:email; kind, such as email or phone, or null; slot, which keeps two values of one field apart (default when it has none); value, a text; sourceEntity, the address of the record it comes from; and rung, the sharing level the organisation placed it at, such as public. Fields come in order of field, then slot. about is the organisation's own description, given only to signed-in people when the organisation is listed for everyone to find, and always to those who hold Control. complete false means the vault holds more than 200 values placed at a sharing level and only the first 200, in the order they were written, were read; fewer fields than that may come, since each one is then filtered for you.

Deeper

Also asked:

How do I read an organisation's public card? Send GET https://id.gilb.com/base/connect/org-card?vault=<vault id, encoded> with no token: the answer holds the fields the organisation shares with everyone.

404 no_online_card is one answer for everything that is not a card you may see: the vault is not an organisation, does not exist, is not a vault, or shows you nothing. It takes as long as any other refusal, so it says nothing about which. Checked on production on 2026-11-11, with no token: the system vaults https://kaizen.gilb.com/base and https://connect.gilb.com/base answered 404 {error:NotFound,code:no_online_card,message:No online card.}.

No vault= answers 400 querystring must have required property 'vault', and any other key 400 querystring must NOT have additional properties. 503 with Retry-After: 5 means the card could not be read this time, and 429 with Retry-After: 1 Too many concurrent reads of this card; retry shortly. means too many signed-in reads of one card at once; wait that many seconds and ask again, with a new proof. The card is never served in part.

The card shows only fields with one text value that the organisation placed at a sharing level: its logo, its parent organisation and its languages are links, not text, and are not on it, and neither is its name. A field written but not yet placed at a level is shown to no one, those who hold Control included. The answer is never kept: cache-control is private, no-store, so a field taken off the card is gone on the next read.

A person's online card is read another way, by the person's address; the answer on connecting a card to the person's own online card shows it in GilbApp. The Developer Guide, GilbPlatform's guide for people who build apps on it, does not cover online cards yet.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11; code read at 498d29a0): src/routes/connect-org-card.ts:1-41 (GET /base/connect/org-card?vault=: 200 card; one 404 for everything else, no existence oracle, REFUSAL_FLOOR_MS; 503 Retry-After 5; 429; 400 vault missing or another key; anonymous callers see the public rung only), :65-75 (NO_ONLINE_CARD_BODY, TOO_MANY_BODY), :103-105 (cache-control private, no-store; vary Authorization), :130-238 (schema vault required, additionalProperties false; bearerFloorSurfacePrincipal; 503 too many writers to verify); src/baseconnect/org-card-read.ts:1-26 (default deny: deed exactly t:Organization; admitted claim types; fact stamped in the vault; a claim with no rung is HELD, never served, including to Control; one value; provenance; the person ladder; does not serve a reference-valued field (logo, parent, languages) nor the name), :54-90 (ORG_CARD_SURFACE connect-org-card/1; MAX_CARD_CANDIDATES 200; field, kind, slot, value, sourceEntity, rung; about; complete), :290-354 (field = the attribute; sorted by field then slot; Control holder sees every placed field), :356-410 (about: signed-in viewers of a publicly listed group, and its Control holders; anonymous never); src/baseconnect/org-card-master.ts:1-130 (fields from the master's a:fieldOf, inline literals only); src/routes/connect-online-card-anchor.ts:1-60, :103-170 (record = the caller's own record, a:sameAs, answer kinds person|organization with vaultId), :488-556 (one 404 no_online_card; 429; 503), :560-720 (record must be on the caller's own vault; answer surface connect-online-card-anchor/1, principal, vaultId, entity, vaultRepresents), :720-728 (401 Sign in required); src/routes/connect-org-find.ts:1-130 (GET /base/connect/org-find?q=, requirePrincipal: DPoP); src/baseconnect/org-find.ts:49 (vaultId per hit); src/routes/connect-org-field-claims.ts:1-30 (an organisation field is written held, with no rung; publishing at a rung is a separate act). Public reads, no token, 2026-11-11: https://id.gilb.com/base/connect/org-card?vault=https%3A%2F%2Fkaizen.gilb.com%2Fbase 404 no_online_card, cache-control private, no-store; vault=https%3A%2F%2Fconnect.gilb.com%2Fbase 404 the same; vault=nothing 404 the same; no vault 400 querystring must have required property 'vault'; with x=1 400 querystring must NOT have additional properties; GET /base/connect/online-card-anchor?record=... 401 {error:Unauthorized,message:Sign in required}; GET /base/connect/org-find?q=gilb 401 This surface requires an authenticated caller (no token presented). its meaning as the approved wording lets them manage who else has access; Row: GilbPlatform.OrgCardRead.

For developers

curl

org-card.sh

# Anyone, with no token: only the fields the organisation shares with everyone.
curl -s "https://id.gilb.com/base/connect/org-card?vault=<vault id, encoded>"
# 200 {"surface":"connect-org-card/1","vault":"<vault id>","fields":[
#        {"field":"a:email","kind":"email","slot":"<slot>","value":"<value>","sourceEntity":"<address>","rung":"public"}],
#      "about":null,"complete":true}
# 404 {"error":"NotFound","code":"no_online_card","message":"No online card."}

# A signed-in person sees what is shared with them too.
curl -s "https://id.gilb.com/base/connect/org-card?vault=<vault id, encoded>" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for this GET and this address>"

TypeScript

read-org-card.ts

// Read an organisation's online card. Without headersFor you get the fields shared with everyone.
// headersFor returns Authorization and a new DPoP proof for one request, for a signed-in person.
type CardField = { field: string; kind: string | null; slot: string; value: string; sourceEntity: string; rung: string };
export type OrgCard = { surface: "connect-org-card/1"; vault: string; fields: CardField[]; about: string | null; complete: boolean };
type HeadersFor = (method: string, url: string) => Promise<Record<string, string>>;

export async function readOrgCard(vaultId: string, headersFor?: HeadersFor): Promise<OrgCard | null> {
  const url = `https://id.gilb.com/base/connect/org-card?vault=${encodeURIComponent(vaultId)}`;
  for (let attempt = 1; attempt <= 3; attempt++) {
    const res = await fetch(url, { headers: headersFor ? await headersFor("GET", url) : {} });
    if (res.status === 200) return (await res.json()) as OrgCard;
    if (res.status === 404) return null; // no card, or nothing you may see: one answer for both
    if (res.status !== 429 && res.status !== 503) throw new Error(`org-card answered ${res.status}: ${await res.text()}`);
    const wait = Number(res.headers.get("retry-after") ?? "5");
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  throw new Error("org-card could not answer; try again later");
}

Checked against GilbApp d529620.