MyJackfruit

Help
Browse topics · For developers

For developers

← For developers

Which token should my app use?

Short answer

Use the sign-in token from the person's e-mail-code sign-in, or, when your server acts as itself, a machine token it asks for with its key.

Before you start

Words used here (1)
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.
Deeper

Also asked:

Which token should my app send? The sign-in token from the person's e-mail-code sign-in, with a new DPoP proof on each request; or, when your server acts as itself, a machine token it asks for with its key.

Is the sign-in standard OAuth or OpenID Connect? Can I use an existing OAuth library? Not OpenID Connect: a person signs in by e-mail code and your app gets a DPoP token (RFC 9449). Only a program's own token uses an OAuth call, /base/oauth/token, and the guide names no OAuth library: use the gilb-signin kit.

A token is the signed credential your app sends with each request so the platform knows who is asking. Both kinds above are bound to a key your app holds: each request carries Authorization: DPoP followed by the token, and a new DPoP proof, a short signed note your app makes for one request, naming its method and address (RFC 9449). A copy of the token is useless without the private key.

The sign-in token acts for a person. Your app sends the public half of its key with the code to POST https://id.gilb.com/base/auth/email/verify-code, and the answer holds token. It reaches only what that person owns or has been given, and lasts 7 days. The sign-in names your app when your app sends its client id, the name the platform gave your app when it was registered, as client in that request; in a browser, on an origin the platform owner approved for your app, the origin names it. A token that names your app carries no owner or operator standing, the extra powers of the people who run GilbPlatform, and only such a token can be traded for an outside service's token.

The machine token acts for your app itself. Your server signs a short assertion with the private key it registered and sends it, with a proof, to POST https://id.gilb.com/base/oauth/token; the token lasts 300 seconds, with no refresh. It reaches nothing until a vault owner binds your app to an AI vault, a small vault that stands for your app, and gives that AI vault access. A page in a browser cannot keep the private key secret, so a page alone cannot use this way.

Use the sign-in token when each person uses your app on their own vaults, and the machine token when your server reads content in your own vault for all your users. The answers on getting a machine token and on how your app's server reads its own vault show the second.

GilbPlatform's own web apps also use two tokens made from a person's browser sign-in at id.gilb.com: a plain Bearer token, bound to no key, from POST /base/auth/session/token, and a DPoP-bound one from POST /base/auth/session/dpop-token, each for 1800 seconds. Your app does not need them: a page on any other origin, an approved one too, is refused with 403.

A plain Bearer token is taken on /lws and /files. On /base addresses the routes that sign a person in, trade tokens, register an app or run the AI chat take nothing else: a plain Bearer token there is treated as coming from no one. Many other /base routes, such as search, writes to a record at its own address, relation reads and the connect routes, also take a plain Bearer token. A token bound to a key never works without its proof: sent without one, it is refused or the call is treated as coming from no one.

One more serves a narrow use: a service token, which your app gets by trading a sign-in token and which only one outside service accepts (the answer on letting a signed-in person use an outside service).

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. 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/email-auth.ts:92-121 (verify-code body: email, code, dpopJwk, client, name, renew), :485-509 (markerForRequest from the approved origin, else body client); src/auth/email-otc.ts:457-462 (sign-in token: mintAccessToken with the key, emailOtcTokenTtlSec, client); src/config/index.ts:649 (7 days); src/auth/issue.ts:61-105 (cnf.jkt :78, azp only when client given :83, ES256, typ at+jwt); src/auth/app-standing.ts:1-30 (an app-held credential has no owner or operator standing); src/auth/outside-service-exchange.ts:178-181 (no azp: unauthorized_client); src/auth/machine-token.ts:94 (300 s), :330-396 (client_credentials, assertion, proof, token_type DPoP, azp = clientId); src/auth/verify.ts:383-423 (no cnf.jkt refused on /base; proof key must match cnf.jkt); src/auth/principal.ts:145-158 (a non-DPoP Authorization on /base is not lifted: anonymous); src/routes/session-token.ts:1-42, :129-130 (1800 s), :399-447 (POST /base/auth/session/token, plain Bearer), :449-481 (POST /base/auth/session/dpop-token, DPoP-bound); src/auth/session-mint-gate.ts:71-90 (403 for an Origin that is not first-party); src/server/cors.ts:577-603 (session bridges first-party only; attested origins never reach them), :107-138 (the Bearer-floor /base set: /base/search, /base/files, /base/e|r/<id>, /relations); src/auth/bearer-principal.ts:14-26, :161-200 (Bearer floor on /lws and /files; a key-bound token without its proof refused, AUTH_REQUIRE_DPOP_FOR_BOUND default on); src/routes/write.ts:47, :74 (PUT /base/e/:id on the Bearer floor); src/routes/search.ts:276, :302; src/routes/read.ts:395-405, :798-810 (relations on the Bearer floor; single reads DPoP-only); the code at 498d29a0 shows: 33 route files (incl. /base/connect/*, /base/tag/*, /base/files, /base/vault/cost). GilbApp ebd9415e (live at https://gilb.com/app/version.json): src/lib/base/token.ts:1-9 (GilbApp uses the 1800 s Bearer bridge). Dev.Guide.SignIn (A 06gkzpwhanxrh55sca1pdkxj88, pack GilbPlatformDeveloperGuide, 2026-11-11; https://appbuilder.gilb.com/base/e/06gkzpwhanxrh55sca1pdkxj88; read for agreement, not copied) Code, TokenLife, Proof, Surfaces, KeySafety, BrowserApps, AppStanding, Programs; Dev.Guide.AppAccess (A 06gqw6jdn9sgbc9rfbfrwc7rec, pack GilbPlatformDeveloperGuide, 2026-11-11; https://appbuilder.gilb.com/base/e/06gqw6jdn9sgbc9rfbfrwc7rec; read for agreement, not copied) intro (own content vs each person's vault), Entry.Server. Rows: Developer.SessionBearerToken, SessionDpopToken, EmailCodeDpopToken, BearerFloorOnNativeRoutes.

Checked against GilbApp d529620.