MyJackfruit

Help
Browse topics · For developers

For developers

← For developers

How does an outside service check who is asking?

Short answer

Get the platform's keys from https://id.gilb.com/base/auth/jwks.json, verify the token's signature, issuer, audience and expiry, then read the person from sub and the app from azp.

Before you start

Your service is registered with GilbPlatform, and you have the address the platform owner stored for it.

Words used here (3)
GilbPlatform
GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
action name
An action name is a short lower-case name an outside service gives one thing it does; a token lists the ones granted to the app.
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. Get the platform's public keys.

    Read the platform's key set, with no token, from:
    https://id.gilb.com/base/auth/jwks.json

    More about this

    It is a JWKS, a JSON Web Key Set: a list of public keys, each with a key id (kid). Today it holds one EC P-256 key for ES256. The same set is at https://id.gilb.com/.well-known/jwks.json. A cache may keep it 300 seconds. Around a change of key the set may also hold the platform's next or previous key, so pick the key by the kid in the token's header. A standard JOSE library, a library for signed JSON tokens such as jose, can fetch the set for you.

  2. Verify the token's signature, issuer, audience and expiry.

    Take the token from the request's Authorization: DPoP header and verify it with your JOSE library: algorithm ES256, issuer (iss) https://id.gilb.com/base/auth, audience (aud) your service's registered address, and an expiry (exp) still in the future.

    More about this

    Refuse the request if any check fails. Compare aud with the address exactly as the platform owner stored it, as a string. The token's header type is at+jwt. It lasts 300 seconds from when it was made, or less if the person's sign-in ends sooner. It is also bound to the app's key: its cnf.jkt is that key's thumbprint, and the app sends a new DPoP proof, a short signed note for one request, with each call. Check that proof as RFC 9449 says; the Developer Guide chapter below lists the checks.

  3. Read who is asking from sub and azp.

    sub is the person's vault address, such as https://<name>.gilb.com/vault, and azp is the client id of the app the person used.

    More about this

    A vault address is the web address that names one vault. sub is never an e-mail address, and every service sees the same sub for the same person. A client id is the name the platform gave an app when it was registered. scope lists the action names granted, separated by spaces: the ones the app asked for, or every action of the service if it asked for none; what each one lets the caller do is up to your service. Take who is asking only from the verified token, never from another header or a field in the request.

Deeper

Also asked:

How does my own server check that a GilbPlatform token is real? Fetch the keys at https://id.gilb.com/base/auth/jwks.json and verify the token's ES256 signature, its issuer https://id.gilb.com/base/auth, its audience, your service's address, and that exp is still in the future.

The token tells your service which person is asking; it gives no access to the person's vault. Its audience is your service's address, and the platform's own vaults accept only tokens made for them. It holds no e-mail address and no data from the vault. An outside service acting for the person in their vault is not built.

The platform has no way to ask whether a token is still good: check the signature and exp. If the person signs out, a token you already have keeps working until it runs out, at most 300 seconds; the platform makes no new one for that sign-in. A suspended or withdrawn service gets no new tokens.

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.OutsideServices, https://appbuilder.gilb.com/base/e/06gwd3evv9s9zaba5fx0d43ybc. 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; includes 5be516b4): src/auth/issue.ts:61-105 (claims: cnf.jkt :78, azp :83, scope, header alg ES256 and typ at+jwt :98, sub :99, iss, aud :101, iat, exp :103); src/auth/dpop.ts:13 (TOKEN_ALG ES256); src/auth/outside-service-exchange.ts:300-316 (sub = the vault WebID, never an e-mail), :297-298 and :400-417 (grantedActions: the token's scope is the granted list; scope left out or empty = every action of the service, in its stored order), :367-375 (expiresInSec = min(300, remaining), audience = service address, client = azp); src/routes/jwks.ts:22-29, :41-44 (next and previous keys), :130-133 (/base/auth/jwks.json and /.well-known/jwks.json); src/auth/verify.ts:221-251 (each trusted issuer pins its own audience: the vault refuses this token); no introspection route (the code shows: no hit). REAL on production per the GilbPlatform handoff of 2026-11-10 (P8): expires_in 300, sub the vault address with no e-mail, azp the app, aud the service address, iss https://id.gilb.com/base/auth, stock jose verify against /base/auth/jwks.json PASS. Public read 2026-11-11: https://id.gilb.com/base/auth/jwks.json 200, cache-control public, max-age=300, one key {kty:EC,crv:P-256,alg:ES256,use:sig}. Dev.Guide.OutsideServices (A 06gwd3evv9s9zaba5fx0d43ybc, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) ServiceChecks, ProofChecks, WhoIsAsking, Keys. Vault address wording as What is a vault's address? (vaults/how-do-i-see-my-vaults-address).

For developers

TypeScript

who-is-asking.ts

import { createRemoteJWKSet, jwtVerify } from "jose";

// The platform's public keys. jose fetches the set.
const keys = createRemoteJWKSet(new URL("https://id.gilb.com/base/auth/jwks.json"));

// Your service's address, exactly as the platform owner stored it.
const MY_ADDRESS = "<your service's registered address>";

export async function whoIsAsking(authorization: string) {
  if (!authorization.startsWith("DPoP ")) throw new Error("not a DPoP token");
  const { payload } = await jwtVerify(authorization.slice(5), keys, {
    algorithms: ["ES256"],
    typ: "at+jwt",
    issuer: "https://id.gilb.com/base/auth",
    audience: MY_ADDRESS,
  });
  // Also check the request's DPoP proof against payload.cnf.jkt (RFC 9449).
  return {
    person: payload.sub, // the vault address, such as https://<name>.gilb.com/vault
    app: payload.azp as string, // the client id of the app the person used
    actions: String(payload.scope ?? "").split(" "),
  };
}

Checked against GilbApp d529620.