← Registering an app and getting it approved
How do I register a client?
Short answer
Make a P-256 key pair, send its public half with your origin and app name to /base/client/register, and keep the clientId.
Before you start
A server or a script of your own that can keep a private key secret.
Words used here (2)
- declared origin
- A declared origin is the web origin a developer says their app is served from, sent at registration; it is a label only.
- GilbPlatform
- GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
Steps
Make a key pair for your app.
On your server or in your script, make a new ECDSA key pair on the P-256 curve, keep the private half there, and never send it to anyone.
More about this
A key pair is two matching keys: your app signs with the private one and sends the public one. The public half is what identifies your app: the platform makes the clientId from it, so the same key always gives the same clientId. Your app's server signs its machine-token requests with the private half. A web page does not use it: it signs its proofs with a key made on the person's device.
Send the registration.
Send JSON with clientPublicKey, declaredOrigin and clientDisplayName, with no sign-in, to:
POST https://id.gilb.com/base/client/registerMore about this
clientPublicKey is the public half as a JWK, a key written as JSON: kty EC, crv P-256, x and y. declaredOrigin is your app's declared origin, the scheme, host and port its pages are served from, such as https://my-app.example; it is a label only and lets nothing through. clientDisplayName is your app's name, up to 256 characters; the sign-in e-mail can show it once your origin is approved. Nobody approves this call.
Keep the clientId.
Keep clientId from the answer; it is your client id, the name the platform gave your app when it was registered.
More about this
The answer is 200 with clientId, created and confersAuthority false. confersAuthority false says what it means: registering gives no access, and a registered app reaches what an unregistered one does. The same key sent again answers 200 with the same clientId and created false and changes nothing, so a wrong origin or name needs a new key. Your app sends the clientId as client when a person signs in, and as iss and sub of its machine-token assertion.
For a web app, ask the platform owner to approve its origin.
Send the clientId and the exact origin your pages are served from to the platform owner, who runs GilbPlatform, and ask for approval.
More about this
Until then a page on that origin is refused by the browser's check before each call, with 403. Only pages in a browser need this: an app's server, a script and a native app that sends no Origin header are not checked. The answer on how a browser app gets the owner's approval says what approval does and does not do.
Deeper
A key that is not EC P-256 answers 400 invalid_client_key, and so does a JWK that holds the private member d; a missing or extra field answers 400 before that. If the platform owner has ended your registration, the same key answers 409 client_registration_ended: register a new key, which gives a new clientId.
Registering gives no access and does not let your origin through. declaredOrigin and clientDisplayName are what you say about your app; nobody checks them, and the platform never lets a request through on them: only the key identifies your app. There is no screen in GilbApp to register an app; the registration is a call.
Once your origin is approved, a request for a sign-in code, POST https://id.gilb.com/base/auth/email/request-code, may carry return_to, an address on that origin, and the e-mail then names your app by its clientDisplayName; an address on any other origin is ignored. The answer on signing in from your app and returning the person to it says more.
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.SignIn, https://appbuilder.gilb.com/base/e/06gkzpwhanxrh55sca1pdkxj88. Its exhibit BrowserApps has the registration; the chapter Dev.Guide.AppAccess, https://appbuilder.gilb.com/base/e/06gqw6jdn9sgbc9rfbfrwc7rec, has it for an app's server. 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; code read at 498d29a0): src/routes/client-registration.ts:1-43 (unauthenticated; confers nothing; does not admit), :65-80 (schema: clientPublicKey, declaredOrigin ≤ 2048, clientDisplayName ≤ 256, additionalProperties false), :87-126 (200 clientId, created, confersAuthority false; 409 client_registration_ended; 400 invalid_client_key); src/auth/client-registry.ts:172-197 (EC P-256 only; private member d refused; 32-byte coordinates), :205-223 (clientId derived from the key), :301-384 (ended registration; create-only, a repeat changes nothing); src/server/app.ts:244-256 (schema refusal: error and message); src/auth/machine-token.ts:205-238 (assertion checked against the registered key; withdrawn client refused); src/server/cors.ts:624-637 (unapproved origin: preflight 403, no CORS headers); src/routes/email-auth.ts:186-232, :340-372 (return_to only on first-party or approved origins; e-mail named by the registered name); src/auth/otc-app-name.ts:50-100 (registered display name); src/auth/send-otc-email.ts:7-20, :89-103. Dev.Guide.SignIn (A 06gkzpwhanxrh55sca1pdkxj88, pack GilbPlatformDeveloperGuide, 2026-11-11; https://appbuilder.gilb.com/base/e/06gkzpwhanxrh55sca1pdkxj88; read for agreement, not copied) BrowserApps; Dev.Guide.AppAccess (A 06gqw6jdn9sgbc9rfbfrwc7rec, pack GilbPlatformDeveloperGuide, 2026-11-11; https://appbuilder.gilb.com/base/e/06gqw6jdn9sgbc9rfbfrwc7rec; read for agreement, not copied) Register, EndUsers (any screen in GilbApp for registering an app ... the registration is a call). Public read: OPTIONS https://id.gilb.com/base/auth/email/verify-code with Origin https://not-approved.example, 2026-11-11: 403 (a preflight, no body, nothing written). Rows: Developer.RegisterClient, Setup.ReturnToApp (return_to part only).
For developers
TypeScript
register-app.ts
import { exportJWK, generateKeyPair } from "jose";
// Run once on your server or in a script. Keep privateJwk in your secret store; never send it.
const { publicKey, privateKey } = await generateKeyPair("ES256", { extractable: true });
const { kty, crv, x, y } = await exportJWK(publicKey);
const privateJwk = await exportJWK(privateKey);
const res = await fetch("https://id.gilb.com/base/client/register", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
clientPublicKey: { kty, crv, x, y }, // the public half only
declaredOrigin: "<origin of your app>",
clientDisplayName: "<name of your app>",
}),
});
// 200: { "clientId": "<clientId>", "created": true, "confersAuthority": false }
const { clientId } = await res.json();
Checked against GilbApp d529620.