# How do I sign in from my app and return the person to it?

Checked 2026-11-15 against GilbApp d5296208bbffa2ab70076e6194f5537c4be1ddf7.

Get your app's origin approved, send the person to GilbPlatform's sign-up page with return\_to, then sign them in from your app by e-mail code.

## Before you start

A web page of your app, on an origin of its own, for the person to come back to.

## Steps

1. Register your app and get its origin approved.

   [Register your app](http://support.gilb.com/help/how-do-i-register-a-client), then send its clientId and your page's exact origin, such as https://my-app.example, to the platform owner, who runs GilbPlatform, [for approval](http://support.gilb.com/help/how-does-a-browser-app-get-the-owners-approval):
   POST https://id.gilb.com/base/client/register

   The origin is the scheme and host of your page, with the port if it has one. clientId is the name the platform gave your app when it was registered; registering gives no access. GilbPlatform sends a person back only to an origin on its list: its own apps, or an origin the platform owner approved for an app. The Developer Guide's chapter Dev.Guide.SignIn tells how to register and ask for approval. An app published at https://&lt;name\>.pages.dev with the connector is approved on its own: skip this step.
2. Send the person to the sign-up page with return\_to.

   Open this address in the person's browser, with your page's full address, URL-encoded, after return\_to=:
   https://gilb.com/onboard/start?return\_to=&lt;your page\>

   The page is headed "Create your vault". GilbPlatform keeps your address for 30 minutes while the person signs in. It must be a full https:// or http:// address whose origin is exactly one on the list: https://gilb.com.evil.com is not https://gilb.com. An address that does not match is dropped with no error, and the person ends on GilbPlatform's own page instead. The path and query of your address are kept; a \#part is dropped. An address that is not a web address, such as one that opens a phone app, cannot be used.
3. Let the person sign in or make their vault there.

   The person signs in there by e-mail code; a new person also chooses a vault name, and GilbPlatform makes the vault.

   When they are signed in, or their vault is live, GilbPlatform sends their browser to your address. Someone who already has a vault goes back the same way, without a second vault. For an approved app, the sign-in e-mail can name your app by the name it was registered with.
4. Sign the person in from your app by e-mail code.

   Back on your page, [ask for a code and trade it for a token](http://support.gilb.com/help/how-do-i-use-the-sign-in-kit), as the Developer Guide's chapter Dev.Guide.SignIn shows:
   POST https://id.gilb.com/base/auth/email/verify-code

   The sign-in on gilb.com stays there: your page gets no token and no cookie from it, so the person types a code once more, now for your app. Send your public key as dpopJwk; in a browser on your approved origin the origin names your app, and elsewhere you send client, your clientId. The other way skips gilb.com: if the person has no vault yet, verify-code answers needsVaultName true; ask for a name and a new code, and send verify-code again with name, and the first vault is made.

## Deeper

GilbApp does the same for a person with no vault: on its card "Create your first vault", the button "Create your vault" opens https://gilb.com/onboard/start in a second window, sends no return\_to, because GilbPlatform's own page already leads back to GilbApp, and waits. "Cancel" stops the wait and "Reopen GilbPlatform window" opens the window again. GilbApp is one of GilbPlatform's own apps, so it shares the sign-in; another app does not.

Nothing on the sign-up page tells the person where they will go back to, and an address that is not on the list fails without a word, so try the return with your own account before you rely on it.

Checked on production on 2026-11-11, without signing in: the page kept a return to https://gilb.com/app/ for 1800 seconds and dropped one to https://example.com. What happens after the code is from GilbPlatform's code.

The full reference is the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapters Dev.Guide.SignIn, https://appbuilder.gilb.com/base/e/06gkzpwhanxrh55sca1pdkxj88, and 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: GilbPlatform 498d29a0 \(live at https://id.gilb.com/version, read 2026-11-11\): src/auth/post-auth-return.ts:1-17 \(return\_to, server-side allowlist, exact origin equality, short-lived HttpOnly cookie, fallback never an error\), :20-24 \(cookie base\_onboard\_return, 30 \* 60 s\), :26-58 \(allowlist: first-party origins, the default redirect's origin, the owner host\), :60-120 \(owner-attested origins joined; "It grants no credentials: the cookie hinge in cors.ts is untouched and an attested origin is still never sent Access-Control-Allow-Credentials"; "Keep allow-credentials and both session bridges owner-list-only"\), :122-160 \(absolute http\(s\) only; exact url.origin; fragment stripped, path and query kept\); src/routes/onboarding.ts:337-371 \(returnOrigins per request\), :407-418 \(body, then cookie\), :454-480 \(GET /onboard/start sets or clears the cookie\), :750-761 \(returning person → dest\), :815-829 \(new vault live → dest\), :833-841 \(legacy verify → dest\), :176-215 \(entry hosts gilb.com, www.gilb.com, id.gilb.com\); src/auth/otc-app-name.ts:50-72 \(the e-mail names an approved third-party app by its registered name; several names → a neutral label\). GilbApp ebd9415e \(live at https://gilb.com/app/version.json, read 2026-11-11\): src/components/VaultsView.tsx:88-98 \("Create your first vault", "Create your vault"\), src/components/OnboardingCard.tsx:14-62 \(second full-chrome window, "Cancel", "Reopen GilbPlatform window"\), src/lib/base/hooks.ts:19-23 \("We still send no \`return\_to\` — the server default already targets this app"\), :456 \(window.open\(ONBOARDING\_URL\)\), src/lib/base/config.ts:396-400 \(https://gilb.com/onboard/start\). Public reads 2026-11-11: https://gilb.com/onboard/start?return\_to=https%3A%2F%2Fexample.com%2Fafter → 200, set-cookie base\_onboard\_return=; Max-Age=0; title "Create your vault — GilbPlatform", h1 "Create your vault". Dev.Guide.SignIn \(A 06gkzpwhanxrh55sca1pdkxj88, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied\) Code, BrowserApps \(register; send clientId and origin to the owner; approval lets the origin through\), ReviewLogin \(in a browser the attested Origin identifies the app; native: send client\). Dev.Guide.GetStarted \(A 06gkzpwfthtgf9py7m3qd5dx50, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied\) Token \(needsVaultName; new code; verify-code with name\). Rows: Setup.ReturnToApp, FirstVaultFromGilbApp. GilbPlatform 0fc5a548 \(https://id.gilb.com/version, read 13 November 2026\): src/routes/publish.ts:460-485 \(an app's https://&lt;name\>.pages.dev origin is registered and approved when it is published; none for a website\); src/publish/admission.ts:1-37; Proc\_v\_i\_c\_PublishPagesDev step 8 \(the platform admits exactly that origin on its own\).

## For developers

### JavaScript: send-to-sign-up.js

```javascript
// Send the person to GilbPlatform's sign-up page. They come back to returnTo
// only when its origin is on GilbPlatform's list (approved for your app).
const returnTo = "https://my-app.example/after-sign-in";
window.location.assign("https://gilb.com/onboard/start?return_to=" + encodeURIComponent(returnTo));
```
