MyJackfruit

Help
Browse topics · For developers

For developers

← Back to How do I refresh a token?

How do I get a machine token, and what can it reach?

Short answer

Sign an assertion with your registered key, post it with a proof to /base/oauth/token; the token reaches only what your AI vault was granted.

Before you start

Your app is registered, and its server holds the private key and the clientId.

Words used here (2)
AI vault
An AI vault is a small vault that stands for your AI; your AI reaches only the vaults you grant it.
field
A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda.
Steps
  1. Sign a client assertion.

    On your server, sign a short JWT with the registered private key: header alg ES256 and typ JWT; claims iss and sub your clientId, aud https://id.gilb.com/base/oauth/token, iat now, exp shortly after, and a new jti.

    More about this

    A client assertion is a short signed token that proves your server holds the registered key; there is no client secret. Use each one once: a second use answers 401 invalid_client, client assertion has already been used (replay rejected). An assertion whose iat is more than 300 seconds old, whose exp has passed or that another key signed is refused with 401 invalid_client, and so is every assertion once the platform owner has withdrawn the registration.

  2. Make a new proof for the token request.

    Make a new DPoP proof for POST https://id.gilb.com/base/oauth/token, signed with the key you will use for every call with this token.

    More about this

    A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449); the answer on making a DPoP proof shows how. The token is bound to the key in this proof, which can be the registered key or another P-256 key your server keeps. A missing or wrong proof answers 400 invalid_request.

  3. Send the token request.

    Send the form, as application/x-www-form-urlencoded, with the proof in the DPoP header:
    POST https://id.gilb.com/base/oauth/token

    More about this

    The fields are grant_type client_credentials, client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer, client_assertion, and scope base.read or base.write (base.read if left out; any other answers 400 invalid_scope). A client_secret field is refused with 400. The answer holds access_token, token_type DPoP, expires_in 300 and scope. The token lasts 300 seconds, with no refresh: ask again with a new assertion and a new proof.

  4. Use the token with a new proof for each call.

    Send Authorization: DPoP and the token, with a new proof for each call, to the host of the vault you read or write, such as https://<name>.gilb.com.

    More about this

    The platform makes your app's identity the first time the app uses a token, and that identity reaches nothing: every call answers as a call from no one would, until a vault owner binds your app to an AI vault and gives that AI vault access. An AI vault is a small vault that stands for your app; it holds no content of its own. Steps 2 to 5 of the answer on how your app's server reads its own vault show how.

Deeper

Also asked:

How does my server get a token when no person is signed in? It signs a client assertion with its registered key and sends it, with a new DPoP proof, to POST https://id.gilb.com/base/oauth/token. The token lasts 300 seconds and reaches only what its AI vault was given.

Once your app is bound and granted, the token reaches what the AI vault was given, and its scope narrows that further: base.read only reads, even where the AI vault may write, and base.write writes only where it was given write. A refused read answers 404, the same as a missing record, and a refused write 403.

A machine token never acts for a person and never carries owner or operator standing, the extra powers of the people who run GilbPlatform. It cannot bind itself to an AI vault, cannot set a vault's type, and cannot make a vault unless its AI vault was given a vault-creation grant. Signing out does not apply to it: POST https://id.gilb.com/base/auth/sign-out answers 400 only a person's sign-in token can end a sign-in here. To stop it, take the grant away; its next request is refused.

Do not pass the token or the private key to a page or a user. If the key leaks, anyone holding it can act as your app: take the grant away at once, then ask the platform owner to move your registration to a new key and to make it the only key (your clientId stays), or register a new key, which gives a new clientId and needs steps 2 to 5 of the answer on how your app's server reads its own vault again, with a new AI vault.

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.AppAccess, https://appbuilder.gilb.com/base/e/06gqw6jdn9sgbc9rfbfrwc7rec. Its step FirstToken has the request and its answers. 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/auth/machine-token.ts:86-94 (assertion at most 300 s old; token 300 s), :114-131, :241-252 (single-use jti, client assertion has already been used (replay rejected)), :193-238 (invalid_client: malformed, unknown or withdrawn client, signature, iss/sub/aud pinned, maxTokenAge 300 s), :272-312 (proof: invalid_request; its embedded jwk becomes cnf.jkt), :330-396 (grant_type, client_assertion_type, scope before the assertion is spent; answer access_token, token_type DPoP, expires_in 300, scope; azp = clientId); src/auth/machine-scope.ts:91-96, :121-144 (base.read, base.write; empty = base.read; anything else unsupported scope); src/routes/machine-token.ts:41-84 (form schema, additionalProperties false: client_secret refused), :95-100 (401 invalid_client, 400 others); src/auth/create-named-vault.ts:84, :93-103, :138-160 (machine credential: no vault without a vault-creation grant); src/routes/vault.ts:439-442 (machine cannot set a vault's purpose-type); src/routes/sign-out.ts:53-56 (400 only a person's sign-in token can end a sign-in here); src/auth/app-standing.ts:1-30 (no owner or operator standing); src/routes/authz.ts:1575 (bind-agent-vault), src/auth/bind-agent-vault.ts:110, :127. Dev.Guide.AppAccess (A 06gqw6jdn9sgbc9rfbfrwc7rec, pack GilbPlatformDeveloperGuide, 2026-11-11; https://appbuilder.gilb.com/base/e/06gqw6jdn9sgbc9rfbfrwc7rec; read for agreement, not copied) FirstToken (fields, assertion claims, scope ceiling, 300 s, first use, refusals), Bind (only the owner; an app cannot bind itself), Read, Write (403 with base.read), EndUsers; Dev.Guide.SignIn (A 06gkzpwhanxrh55sca1pdkxj88, pack GilbPlatformDeveloperGuide, 2026-11-11; https://appbuilder.gilb.com/base/e/06gkzpwhanxrh55sca1pdkxj88; read for agreement, not copied) Programs. Key rotation: GilbPlatform 498d29a0 scripts/approve-client.ts:15-16, :260-265 (set-next-key <clientId> <public JWK>, promote-next-key <clientId>, run only by the platform owner against the identity store); src/auth/client-registry.ts:613-660 (setClientNextPublicKey: The client id stays the id derived from the first key); src/auth/machine-token.ts:213-217 (an assertion signed by either key is accepted until the next key is promoted, same client id). Registration itself stays create-only (src/auth/client-registry.ts), so a wrong origin or name still needs a new key. Rows: Developer.MachineClientToken, MachineTokenScope, AppHeldCredential (machine half).

For developers

TypeScript

app-token.ts

import { SignJWT, importJWK, type JWK } from "jose";

const TOKEN_URL = "https://id.gilb.com/base/oauth/token";

// clientId from the registration; privateJwk is the app's private P-256 key, kept on the server.
// dpopProof is a new proof for POST TOKEN_URL, made with the key you use for every call with this token.
export async function appToken(clientId: string, privateJwk: JWK, dpopProof: string, scope: "base.read" | "base.write") {
  const key = await importJWK(privateJwk, "ES256");
  const now = Math.floor(Date.now() / 1000);
  const assertion = await new SignJWT({})
    .setProtectedHeader({ alg: "ES256", typ: "JWT" })
    .setIssuer(clientId)
    .setSubject(clientId)
    .setAudience(TOKEN_URL)
    .setIssuedAt(now)
    .setExpirationTime(now + 60)
    .setJti(crypto.randomUUID()) // a new one every time: an assertion works once
    .sign(key);
  const res = await fetch(TOKEN_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded", DPoP: dpopProof },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      client_assertion: assertion,
      scope,
    }),
  });
  if (res.status !== 200) throw new Error(`token call answered ${res.status}`);
  return (await res.json()) as { access_token: string; token_type: "DPoP"; expires_in: number; scope: string };
}

Checked against GilbApp d529620.