MyJackfruit

Help
Browse topics · Sign-in and tokens

Sign-in and tokens

← Back to How do I grant access by API (person, group, whole vault, public)?

How do I use the sign-in kit?

Short answer

Install gilb-signin, make a key pair, ask for a code, trade it for a token, then sign each request with dpopHeaders.

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 (5)
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.
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.
approved origin
An approved origin is the exact web origin the platform owner approved for one registered app; only it lets that app's pages through.
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. Install the sign-in kit.

    In your app's folder, run:
    npm install gilb-signin

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

  2. 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. The kit makes the private key so that it cannot be copied out, and it is gone when the page closes or reloads; the person then signs in again. Do not write it to localStorage or to disk. A key held elsewhere, such as in the iOS Secure Enclave, can take its place: pass publicJwk and a sign function that returns the raw 64-byte signature.

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

    It succeeds on 200, also for an address that has no account. It throws SignInRefusedError, with the status, when the platform refuses, and SignInUnreachableError when it cannot be reached. Its optional third value, returnTo, is an address the e-mail leads back to; it counts only on GilbPlatform's own origins and on an origin the platform owner approved for your app.

  4. Trade the code for a token.

    Call verifySignInCodeHttp with https://id.gilb.com, the e-mail address, the code and key.publicJwk; the answer holds token, principal and needsVaultName.

    More about this

    A wrong, expired or used code throws CodeRejectedError. 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. Version 0.3.0 sends no client and no renew: to name your app or renew the sign-in, send POST https://id.gilb.com/base/auth/email/verify-code yourself. It also asks the browser to send cookies, and for a page on an approved origin the platform's answer does not allow that, so the browser refuses the answer and the kit throws SignInUnreachableError, as if the platform could not be reached: there, pass a transport that sends no cookies, as the example below does.

  5. Sign each request with dpopHeaders.

    For every request, call dpopHeaders(key, token, method, url) and send the two headers it returns, Authorization and DPoP.

    More about this

    It makes a new DPoP proof, a short signed note your app makes for one request, naming its method and address (RFC 9449), and takes the address from url, so pass the exact address you call. Send a vault's records to the vault's own host, such as https://<name>.gilb.com, and sign-in, registration and new vaults to https://id.gilb.com. Read the token's exp claim, the expiry time inside the token, to know when it runs out.

Deeper

Also asked:

Can my app sign people in with a passkey? No: GilbPlatform takes passkey sign-ins only from pages at https://gilb.com, such as GilbApp, so your app signs people in with the e-mail code.

How do I sign a person out of my app? Send POST https://id.gilb.com/base/auth/sign-out with headers from dpopHeaders, then forget the token and the key. It answers 204, and the person's tokens on that key are refused within seconds.

With React, the kit also has a whole sign-in card: import SignInCard from gilb-signin and the styles from gilb-signin/signin.css, and give it app, with your app's name, title, origin and return address, auth, the sign-in calls it makes, and onSignedIn. In a native shell, such as Capacitor, pass your own transport, the function that sends a request, as the last value of requestSignInCode and verifySignInCodeHttp; the DPoP helpers send nothing. The package names no licence (its licence field says UNLICENSED): the Developer Guide tells you to use it, and for anything beyond that ask Kai Gilb in writing through GilbPlatform (GilbPlatform.Licence.Permission).

Version 0.3.0 has no call to sign the person out or to renew a sign-in. To sign out, send POST https://id.gilb.com/base/auth/sign-out with headers from dpopHeaders, then forget the token and the key; the answer on refreshing a token shows renewal. The package also holds a guide of its own, THIRD-PARTY-GUIDE.md, last measured against the platform on 2026-09-24.

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. The answer on getting started with the developer guide follows the same steps. It can be read with no sign-in, as data for programs and AIs rather than as a web page.

Source: gilb-signin 0.3.0 (npm latest, read https://registry.npmjs.org/gilb-signin 2026-11-11; gitHead d7682177 = tag v0.3.0; code read at d7682177): package.json (version 0.3.0; exports ., ./core, ./signin.css; react optional peer; files src, README.md, THIRD-PARTY-GUIDE.md, CHANGELOG.md); src/core.ts:19-45 (headless exports); src/dpop.ts:55-61 (publicJwk + sign), :84-95 (generateDpopKeyPair, non-extractable, in memory), :163-166 (64-byte raw signature), :179-189 (dpopHeaders: Authorization DPoP + a new proof with ath); src/http.ts:20-42 (requestSignInCode(origin, email, returnTo?, productName?, opts): SignInUnreachableError, SignInRefusedError on non-2xx), :116-149 (verifySignInCodeHttp(origin, email, code, dpopJwk, name?, productName?, opts): body email, code, dpopJwk, name; no client, no renew; credentials include; 401 CodeRejectedError); src/transport.ts (fetchTransport passes req.credentials; HttpOptions.transport); src/types.ts (SignInApp, SignInAuth, the three errors); src/index.ts (SignInCard); src/SignInCard.tsx:23-35 (props app, auth, onSignedIn); THIRD-PARTY-GUIDE.md (Last measured against production: 2026-09-24; key dies with the page, §7). GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11; code read at 498d29a0): src/server/cors.ts:605-622, :940-946 (Access-Control-Allow-Credentials only for first-party origins; an approved third-party origin gets none, so a browser drops a credentialed answer, per the CORS check of the Fetch standard); src/routes/email-auth.ts:92-121 (client and renew exist on verify-code), :186-232 (returnTo origins); src/routes/sign-out.ts. The code library unit KaiGilb/GilbPlatformCode units/signin at 7a40fd01 (public, read 2026-11-11), src/http.ts:125-190 (credentialsForPage: "An attested third-party origin does not get that header, so \include\ makes the browser discard the JSON"), confirms the cookie fault; its renewal is only on branch kaizen/signin-renew (not merged). Dev.Guide.GetStarted (A 06gkzpwfthtgf9py7m3qd5dx50, pack GilbPlatformDeveloperGuide, 2026-11-11; https://appbuilder.gilb.com/base/e/06gkzpwfthtgf9py7m3qd5dx50; read for agreement, not copied) Install, Key, Code, Token, FindVault. DPoP gloss (253). The example sign-in.ts is written here from the kit's 0.3.0 signatures; not run.: gilb-signin 0.3.0 src/http.ts (verifySignInCodeHttp sends credentials include; a fetch failure is caught and thrown as SignInUnreachableError); GilbPlatform 498d29a0 src/server/cors.ts:605-622, :940-946 (allow-credentials for first-party origins only), so the browser refuses the answer.: npm view [email protected] license, read 2026-11-11: UNLICENSED (package.json license: UNLICENSED); GilbPlatform.Licence rule 11 Permission ("For any use these terms do not allow, ask Kai Gilb in writing through GilbPlatform."). Row: Developer.UseSignInKit.

For developers

TypeScript

sign-in.ts

import {
  generateDpopKeyPair, requestSignInCode, verifySignInCodeHttp, dpopHeaders, fetchTransport,
  type TransportRequest,
} from "gilb-signin/core";

const ID = "https://id.gilb.com";
// A page on your approved origin: send no cookies, or the browser drops the verify-code answer.
const opts = {
  transport: (url: string, req: TransportRequest) => fetchTransport(url, { ...req, credentials: "omit" }),
};

const key = await generateDpopKeyPair(); // in memory only

export async function askForCode(email: string) {
  await requestSignInCode(ID, email, undefined, "<name of your app>", opts);
}

export async function signIn(email: string, code: string) {
  const res = await verifySignInCodeHttp(ID, email, code, key.publicJwk, undefined, "<name of your app>", opts);
  return res; // res.token; res.needsVaultName true: no vault yet
}

export async function read(token: string, recordUrl: string) {
  // recordUrl is on the vault's own host. A new proof for every request.
  return fetch(recordUrl, { headers: await dpopHeaders(key, token, "GET", recordUrl) });
}

Checked against GilbApp d529620.