# How do I refresh a token?

Checked 2026-11-15 against GilbApp d5296208bbffa2ab70076e6194f5537c4be1ddf7.

Send renew true at sign-in, keep the renew credential, send it to /base/auth/email/renew before it expires, then keep the new token and credential.

## Before you start

Your app is a web page on [an origin the platform owner approved](http://support.gilb.com/help/how-does-a-browser-app-get-the-owners-approval) for your app; an app [published at its pages.dev address](http://support.gilb.com/help/how-do-i-publish-my-app-from-the-terminal) with the connector is approved on its own.

## Steps

1. Send renew true when the person signs in.

   Add renew true to the body of POST https://id.gilb.com/base/auth/email/verify-code, sent from your page with the e-mail address, the code and dpopJwk.

   This starts a renewable sign-in. renewWindowSec, the time the sign-in lasts, which each renewal starts again, is optional: at least 300 seconds, and 14 days if you leave it out; more than 14 days counts as 14 days. Below 300 the answer is 400 "renewWindowSec must be an integer of at least 300 seconds", and the code is not used up. From a native app that sends no Origin header, or from GilbPlatform's own apps, the sign-in works as it does without renew, and the answer has no renew fields. With renew, the first token lasts no longer than the window.
2. Keep the renew credential.

   Keep renew and renewExpiresAt from the answer, beside token and the key pair.

   renew is the renew credential, a secret that starts with rsi1. and works only with your key and from your origin. renewExpiresAt is when the sign-in ends if it is not renewed. Treat renew like the private key: never write it where another page or person can read it. The platform takes each renew credential once, and the one before it once more within 60 seconds, so a retry after a lost answer works; any other old one ends the whole sign-in and every token on that key. So when two tabs or devices share one credential, let one renew at a time and keep the credential in one place.
3. Send the renew credential before it expires.

   Send POST https://id.gilb.com/base/auth/email/renew from the same page, with the JSON body renew and the credential, and [a new DPoP proof](http://support.gilb.com/help/how-do-i-make-a-dpop-proof-for-each-request) signed by the same key, with no ath.

   The proof names POST and that address. The browser sends your origin, which must be the one the sign-in started on. The token does not go with it, so this works after the token has run out, as long as renewExpiresAt has not passed. Every refusal is the same 401 "renewal refused": ask the person for a new code. 503 "the ended sign-in could not be recorded" means send the same renewal once more; it then answers 401, and you ask for a new code.
4. Keep the new token and renew credential.

   Replace token, renew and renewExpiresAt with the ones in the answer, and use the new token from now on.

   The new token lasts 7 days or the window, whichever is shorter, and renewExpiresAt moves to the window from now, so a sign-in renewed at least once in each window stays signed in. The old token keeps working until its own expiry. The answer also holds principal, the identity the person acts as.

## Deeper

Also asked:

How do I refresh a token so people stay signed in? Send renew true at sign-in, keep the renew credential, and send it to POST https://id.gilb.com/base/auth/email/renew before the sign-in ends; then keep the new token and credential it gives back.

Only a web page on an approved origin can renew a sign-in. Every other token is asked for again the way it was got, and there is no other refresh: a person's sign-in token by a new e-mail code, after 7 days; [a machine token](http://support.gilb.com/help/how-do-i-get-a-machine-token-and-what-can-it-reach) with a new assertion and a new proof, after 300 seconds; [a service token](http://support.gilb.com/help/how-do-i-let-a-signed-in-person-use-an-outside-service-from-my-app) by trading the sign-in token again, after at most 300 seconds. GilbPlatform's own web apps ask POST /base/auth/session/token again while the person's browser sign-in lasts.

To end a sign-in, send POST https://id.gilb.com/base/auth/sign-out with the person's token and a new proof. 204 means every sign-in token on that key made until then is refused, by vaults within about 5 seconds, and the renewable sign-in ends too; then forget the token, the renew credential and the key. 503 "the ended sign-in could not be recorded" means nothing ended: send it again. When the person signs out, a service token already given keeps working at the service until it runs out, at most 300 seconds.

The Developer Guide, GilbPlatform's guide for people who build apps on it, has the sign-out call in its chapter Dev.Guide.SignIn, https://appbuilder.gilb.com/base/e/06gkzpwhanxrh55sca1pdkxj88. Its exhibit StaySignedIn, https://appbuilder.gilb.com/base/e/06gwy4emx9ym93q17m0agvadnm, holds every renewal request and answer; its examples are marked "Not yet verified on production". 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\) \(contains PR \#701, renewable sign-in, merge 498d29a0; changes/platform/701-renewable-sign-in.md: "keep a person signed in for up to 14 days; each renewal starts the time again"\): src/routes/email-auth.ts:92-121 \(renew, renewWindowSec\), :428-447 \(window checked before the code is used; 400 "renewWindowSec must be an integer of at least 300 seconds"; capped at 14 days; default 14 days\), :295-332 \(family only for an exact, approved, non-first-party Origin; else no renew fields\), :556-562, :572, :623, :639 \(renew and renewExpiresAt added to the answer\); src/auth/renewable-sign-in.ts:1-56, :75-85, :190-197 \(isExactOrigin\), :498-531 \(start: expiresAt = now + window\), :641-672 \(rotation, 60 s grace, new expiresAt = now + window\); src/routes/renew-sign-in.ts:1-12, :26-31 \(401 "renewal refused" for every refusal\), :33-44 \(503 "the ended sign-in could not be recorded"\), :56-82 \(approved non-first-party origin only\), :99-155 \(proof from the family key, origin match, new token = min\(emailOtcTokenTtlSec, remaining window\), answer token, renew, renewExpiresAt, principal; the old token is not ended\); src/auth/dpop-nonce.ts:143-208 \(proof with no ath, no nonce\); src/server/cors.ts:333-341 \(renew path: content-type and dpop, no credentials\); src/routes/sign-out.ts:1-104 \(POST /base/auth/sign-out: 204, ends the device key and the families; 503 "the ended sign-in could not be recorded"\); src/auth/ended-sign-in-set.ts:72, :185, :238-263 \(5 s reload, "sign-in ended"\); src/auth/machine-token.ts:94; src/auth/outside-service-exchange.ts:367-382 \(service token at most 300 s, no refresh token\); src/routes/session-token.ts:37-41, :399-447; src/auth/browser-session.ts:119-124 \(browser sign-in 30 days, sliding\). Dev.Guide.SignIn \(A 06gkzpwhanxrh55sca1pdkxj88, pack GilbPlatformDeveloperGuide, 2026-11-11; https://appbuilder.gilb.com/base/e/06gkzpwhanxrh55sca1pdkxj88; read for agreement, not copied\) TokenLife \("There is no refresh for an app outside the platform's own sites": out of date since PR \#701; report\), Revocation. Dev.Guide.OutsideServices.SignOut \(A 06gwd3g0d9s573sv540ttxff50\). Replaces capability row Security.TokenOutlivesLogoutUntilExpiry \(no longer true as worded\). Rows: Developer.TokenRefreshByReMint, Security.TokenOutlivesLogoutUntilExpiry \(both need rewording\). GilbPlatform 0fc5a548 \(https://id.gilb.com/version, read 13 November 2026\): src/routes/publish.ts:460-485; src/routes/email-auth.ts:440-446; src/routes/renew-sign-in.ts:1-12, :26-44, :125-141 \(a reused old credential ends the sign-in; 503 when that could not be recorded, the next try finishes it and answers 401\). Dev.Guide.SignIn.StaySignedIn \(https://appbuilder.gilb.com/base/e/06gwy4emx9ym93q17m0agvadnm, © 2026 Kai Gilb / GilbPlatform, CC BY 4.0, read 13 November 2026: "When you get this answer, ask the person for a new code."; 503: "send the same renewal again … That try answers 401 renewal refused. Then ask the person for a new code."; "let one tab renew at a time"; examples "Not yet verified on production"\).

## For developers

### TypeScript: renew.ts

```typescript
// Renew a sign-in from a page on your approved origin.
// key: the same key pair the sign-in token is bound to. dpopProof: a proof maker as in the answer on DPoP proofs,
// called with no token, so the proof carries no ath.
const RENEW = "https://id.gilb.com/base/auth/email/renew";

type Signed = { token: string; renew: string; renewExpiresAt: string };

export async function renewSignIn(
  current: Signed,
  key: { publicJwk: object; privateKey: CryptoKey },
  dpopProof: (key: { publicJwk: object; privateKey: CryptoKey }, method: string, url: string) => Promise<string>,
): Promise<Signed> {
  if (Date.parse(current.renewExpiresAt) <= Date.now()) throw new Error("sign-in ended: ask for a new code");
  const res = await fetch(RENEW, {
    method: "POST",
    headers: { "Content-Type": "application/json", DPoP: await dpopProof(key, "POST", RENEW) },
    body: JSON.stringify({ renew: current.renew }),
  });
  if (res.status === 503) throw new Error("not recorded: send it again");
  if (res.status !== 200) throw new Error("renewal refused: ask for a new code");
  const next = await res.json(); // { token, renew, renewExpiresAt, principal }
  return { token: next.token, renew: next.renew, renewExpiresAt: next.renewExpiresAt };
}
```
