← More from code, and code examples
How do I get started with the developer guide?
Short answer
Install the sign-in kit, make a key, sign in by e-mail code, find your vault, create a record and read it back.
Before you start
You can read mail sent to your e-mail address, and you can build TypeScript, for example with Vite or esbuild.
Words used here (7)
- record
- A record is one piece of data with its own address, such as a person, a place, a thing or a note.
- GilbPlatform
- GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
- sign-in code
- A sign-in code is a 6-digit number GilbPlatform e-mails to you; typing it proves the address is yours and signs you in.
- 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.
- vault name
- A vault name is the short name your vault is known by on GilbPlatform: small letters and digits, the first part of its address.
- vault's address
- A vault's address is the web address that names one vault, made from the vault's name, such as https://example-name.gilb.com/vault.
- 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.
Steps
Install the sign-in kit.
In your app's folder, run:
npm install gilb-signinMore about this
The sign-in kit, gilb-signin, is GilbPlatform's library that signs a person in and makes the proof each request needs; npm is the package installer that comes with Node.js. Import from gilb-signin/core if you do not use React. The kit is published as TypeScript source only, so plain Node stops before any code runs, with the error ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING: build your code with a bundler that compiles TypeScript, such as Vite or esbuild, or run it with a TypeScript runner. The version on npm on 2026-11-11 is 0.3.0.
Make a key pair.
Call generateDpopKeyPair() from the kit, and keep the key pair in memory only.
More about this
A key pair is two matching keys: your app signs with the private one and sends the public one when the person signs in. Every token the platform gives your app is then bound to this key, so each request carries a new DPoP proof, a short signed note your app makes for one request, naming its method and address (RFC 9449). Do not write the private key to localStorage or to disk; the kit makes it so that it cannot be copied out.
Ask for a sign-in code.
Call requestSignInCode with https://id.gilb.com and the person's e-mail address; the code arrives by e-mail, never in the answer.
More about this
The answer is 200 with requested true, also for an address that has no account. On production the mail arrived about 8 seconds later. Requests sent too fast, or past the send limit, also answer 200 but send nothing, so wait for the mail rather than ask again.
Trade the code for a token.
Call verifySignInCodeHttp with https://id.gilb.com, the e-mail address, the code and the public half of your key; the answer holds token, the sign-in token, and principal, the identity the person acts as.
More about this
The code works once and stops after 10 minutes; a wrong, expired or used code answers 401, and after 5 wrong codes the address is locked for a while. The token lasts 7 days, or until the person signs out; read its exp claim, the expiry time inside the token. There is no refresh in these steps: when it runs out, the person asks for a new code. If needsVaultName is true, the person has no vault yet: ask for a new code and call verifySignInCodeHttp again with a vault name as its fifth value; the answer then holds vault and vaultId, such as https://<name>.gilb.com/vault.
Find the person's vault.
Fetch https://id.gilb.com/lws/vaults with the token and a new proof, made by the kit's dpopHeaders, and take the vaultId you want.
More about this
Each entry carries vaultId, name and modes, such as read and write. A vaultId can end in /vault or in /base; use it as given. With no token the same call answers 200 with an empty list, not 401, so an empty list can also mean that the request carried no sign-in.
Create a record in that vault.
Send POST to https://<name>.gilb.com/lws/vault/<the vault's address, encoded>/c with a JSON body that holds facts, such as a:title; the answer is 201, with the record's address in its location header.
More about this
Send it to the vault's own host, the start of its address, such as https://<name>.gilb.com. Encoded means written with encodeURIComponent, so the address fits in one part of the path. Fact names such as a:title come from GilbVeda, the shared vocabulary every app uses. Add a type, such as t:Note, to say what kind of record it is; without one the record reads back as t:UntypedEntity. A body with no facts at all answers 400.
Read the record back.
Send GET to the record's address with the token and a new proof; the answer is 200 with an ETag header.
More about this
An ETag is a fingerprint of the record's current state. Keep it and send it in If-Match when you change or end the record: if someone changed it in between, the platform answers 412 and changes nothing, instead of overwriting their change. Signed-in reads answer Cache-Control: private, no-store. If your app keeps a copy of records on a device, go on with the guide's chapter Dev.Guide.Sync.
Check the change log for changes your app can see.
Read the guide's chapter Dev.Guide.ChangeLog, https://appbuilder.gilb.com/base/e/06gkzpwz75yth2yj8drahdnk00, newest entry first.
More about this
Each entry gives the time in UTC, the platform revision, what changed, what your app should do and the chapter that holds it, and says what was proved on production. For example, since 2026-11-10 a sign-in token stops working when the person signs out; before, it worked until its exp.
Deeper
Also asked:
Where is the developer documentation? In the Developer Guide, GilbPlatform's guide for people who build apps on it: start at Dev.Guide.Overview, https://appbuilder.gilb.com/base/e/06gkzpwebxv8ncqr4qd7egmt58, then Dev.Guide.GetStarted. Anyone can read it without signing in.
What is the quickest way to make my first API call? Follow the steps below: install the sign-in kit, sign in by e-mail code, then ask https://id.gilb.com/lws/vaults for your vaults, with the token and a new proof.
Which languages can I use? Is there an SDK for TypeScript, Python or others? The one kit is gilb-signin, for TypeScript; the guide names none for Python or other languages. The calls are plain HTTP, so any language that can send HTTPS requests and make ECDSA P-256 signatures can use them.
Is there a test environment, or do I develop against the live platform? You develop against the live GilbPlatform, with your own vault: the guide names no separate test platform, and what you write is saved for real. To run GilbPlatform on your own servers, write to [email protected].
Where is the full list of errors and limits? In one table of the guide, Dev.Guide.Errors, https://appbuilder.gilb.com/base/e/06gkzpwxmnxf90zcc3mzc757xg; each entry says what to do. Calls the guide does not cover yet, such as minting, are answered only on their own pages here.
Where are complete code examples I can copy? The guide has code to copy for each step, as in Dev.Guide.GetStarted, and many developer answers here end with a code example. There is no single list of examples.
Is there an API reference, such as an OpenAPI file? There is no OpenAPI file. The API reference is the Developer Guide itself, with every call (to create, read, change or delete a record), field and answer in its chapters, and every error and limit in Dev.Guide.Errors.
How do I make test users or test vaults for my app? Sign up extra accounts with other e-mail addresses you can read, and give each its own vault; there is no test platform. For an app-store review or a named tester, the platform owner can issue a review login: ask at [email protected].
These steps work against the live GilbPlatform, with your own vault, and are the guide's chapter Dev.Guide.GetStarted told short: the guide has the code for each step and says which steps were proved on production. The rules for addresses, writing and reading are in its chapters Dev.Guide.Addresses, Dev.Guide.Writing and Dev.Guide.Reading; errors and limits are in one table, Dev.Guide.Errors.
The guide is open under CC BY 4.0; anyone may read, copy, adapt, share it and give it to an AI, with credit. A sign-in token reaches only what the person owns or has been given, and an app that is not on an approved origin cannot call the platform from a page in a browser: the guide's chapter Dev.Guide.SignIn says how a web app is approved.
The full reference, with every field and every answer, is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapter Dev.Guide.GetStarted, https://appbuilder.gilb.com/base/e/06gkzpwfthtgf9py7m3qd5dx50. It can be read with no sign-in, as data for programs and AIs rather than as a web page.
Source: Dev.Guide.GetStarted (A 06gkzpwfthtgf9py7m3qd5dx50, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied): Entry.Email, Entry.Runtime, steps Install (npm install gilb-signin, gilb-signin/core, 0.3.0), Key (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING; bundler or TypeScript runner), Code (It arrives by email. It is never in the answer; about 8 seconds), Token (needsVaultName; new code and name; vault, vaultId), FindVault (vaultId may end /vault or /base; no token: 200 empty list), Create (vault's own host, encoded vault address, 201, location; no type: t:UntypedEntity), ReadBack (200, ETag, Cache-Control private, no-store), Next (Dev.Guide.Sync), Exit.Done. Dev.Guide.SignIn (A 06gkzpwhanxrh55sca1pdkxj88, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied): Code (401), CodeLimits (5 wrong codes lock; too fast or past the cap: 200, nothing sent; 10 minutes), TokenLife (7 days, exp, no refresh; the chapter's no refresh is the older wording: GilbPlatform 498d29a0 src/routes/email-auth.ts:411-470, :546-562 lets verify-code with renew: true start a renewal, a window of up to 14 days, only for an origin the owner approved, which these steps do not use, so the page says no refresh in these steps:), Proof, KeySafety (not localStorage or disk), Revocation (sign-out since 5be516b4), BrowserApps (approved origin). Dev.Guide.Writing (A 06gkzpwmgnzph1fb6jp7gf87c0, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied): FactsKey (no facts: 400), ETag, IfMatch (412, changes nothing). Dev.Guide.ChangeLog (A 06gkzpwz75yth2yj8drahdnk00, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied): entry fields (Key UTC, Revision, What changed, What your app should do, Chapter), Entry14 (sign-out, 2026-11-10, 5be516b4). Dev.Guide.Overview (A 06gkzpwebxv8ncqr4qd7egmt58, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied): ReadNext. gilb-signin v0.3.0 (tag v0.3.0; npm view gilb-signin version 2026-11-11: 0.3.0, latest): src/http.ts:20-40 (requestSignInCode(origin, email, ...), POST /base/auth/email/request-code), :110-140 (verifySignInCodeHttp(origin, email, code, dpopJwk, name?); token, principal, needsVaultName), src/dpop.ts:75-90 (generateDpopKeyPair: non-extractable private key; publicJwk), :170-191 (dpopHeaders(key, token, method, url)), package.json exports ./core. GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11; code read at 498d29a0): src/auth/email-otc.ts:64 (CODE_TTL_MS 10 minutes). Capability rows Capability.Developer.GetStartedWithGuide (Capability-Developer-GilbSupport.md:141), Capability.Developer.FollowClientChangeLog (142). Shared: DPoP gloss, CC BY 4.0 sentence, guide sentence. The code example is written here from the kit at v0.3.0 and the chapter, with placeholders only; not copied. Read 14 November 2026: Dev.Guide.Overview (A 06gkzpwebxv8ncqr4qd7egmt58, pack GilbPlatformDeveloperGuide) WhatItIs, ReadNext; Dev.Guide.GetStarted Entry.Runtime; Dev.Guide.Errors (A 06gkzpwxmnxf90zcc3mzc757xg); the live answer Can I have a test version and a live version of my app at the same time?
For developers
TypeScript
get-started.ts
import { generateDpopKeyPair, requestSignInCode, verifySignInCodeHttp, dpopHeaders } from "gilb-signin/core";
const ID = "https://id.gilb.com";
const email = "<your e-mail address>";
// Step 2: a key pair, kept in memory only.
const key = await generateDpopKeyPair();
// Step 3: the code arrives by e-mail, never in the answer.
await requestSignInCode(ID, email);
// Step 4: trade the code for a sign-in token bound to the key.
const code = "<the 6-digit code from the e-mail>";
const res = await verifySignInCodeHttp(ID, email, code, key.publicJwk);
if (res.needsVaultName) throw new Error("No vault yet: ask for a new code and send a vault name as the fifth value.");
const token = res.token!;
// Step 5: the vaults the person can reach. Pick the one you want.
const listUrl = `${ID}/lws/vaults`;
const list = await fetch(listUrl, { headers: await dpopHeaders(key, token, "GET", listUrl) });
const { vaults } = await list.json();
const vaultId: string = vaults[0].vaultId;
// Step 6: create a record on the vault's own host.
const createUrl = `${new URL(vaultId).origin}/lws/vault/${encodeURIComponent(vaultId)}/c`;
const created = await fetch(createUrl, {
method: "POST",
headers: { ...(await dpopHeaders(key, token, "POST", createUrl)), "content-type": "application/json" },
body: JSON.stringify({ type: "t:Note", facts: { "a:title": "my first record" } }),
});
const recordUrl = created.headers.get("location")!;
// Step 7: read it back and keep the ETag.
const read = await fetch(recordUrl, { headers: await dpopHeaders(key, token, "GET", recordUrl) });
const etag = read.headers.get("etag");
Checked against GilbApp d529620.