← Back to Which token should my app use?
How do I let a signed-in person use an outside service from my app?
Short answer
Get the service registered, look it up by its service id, trade the person's sign-in token for a service token, and call the service.
Before you start
Your app is registered with GilbPlatform, and the person signed in through your app by e-mail code. The person has a vault.
Words used here (5)
- service id
- A service id is the short code GilbPlatform makes for an outside service when the platform owner registers it; apps name the service by it.
- 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.
- 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
Ask the platform owner to register the service.
Only the platform owner, who runs GilbPlatform, can register an outside service; there is no screen and no HTTP route for it. Make sure your app's client id, the name the platform gave your app when it was registered, is on the service's list of apps.
More about this
An outside service is a server that is not part of GilbPlatform, for example one that removes a photo's background. The answer on how to get an outside service registered says what the owner needs. The owner gives back the service id, 26 lower-case letters and digits that name the service; your app uses it in steps 2 and 3. A service the owner has suspended or withdrawn gets no new tokens.
Look up the service by its service id.
Fetch the service's signed answer from the platform, with no token:
GET https://id.gilb.com/base/service/<service id>More about this
The answer is a JWT, a signed JSON web token, of type outside-service+jwt, holding the service's id, address and action names. Check its signature with the platform's keys at https://id.gilb.com/base/auth/jwks.json, check that its issuer is https://id.gilb.com/base/auth and that the id is the one you asked for, then use only the address inside it. Never send a person's token to an address taken from user input, a token or a redirect; fetch only from https://id.gilb.com and follow no redirect. The answer is good for 24 hours, and a cache may keep it 300 seconds. An unknown, suspended or withdrawn service answers 404 not found.
Trade the person's sign-in token for a service token.
Send this form, with a new DPoP proof signed by the key the sign-in token is bound to:
POST https://id.gilb.com/base/oauth/tokenMore about this
The sign-in token is the one your app got when the person signed in by e-mail code. A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449). Send the fields as application/x-www-form-urlencoded: grant_type urn:ietf:params:oauth:grant-type:token-exchange (the token exchange of RFC 8693); subject_token the sign-in token; subject_token_type urn:ietf:params:oauth:token-type:access_token; and resource the service id. The resource is never the service's address: an address answers 400 invalid_target. The answer holds access_token, the service token, with token_type DPoP, expires_in and scope, the actions granted.
Call the service with the service token and a new proof.
Send your request to the address from step 2, with the header Authorization: DPoP followed by the service token, and a new DPoP proof for that request, signed with the same key.
More about this
Only that one service accepts the token. It lasts 300 seconds, or less if the sign-in token ends sooner. There is no refresh token: when it runs out, send the trade in step 3 again; the person does not sign in again. To ask for fewer actions, add scope to the trade with some of the service's action names, separated by spaces; left out, you get every action. The service learns which person is asking, by their vault address, and which app asked; it gets no access to the person's vault.
Deeper
Only a sign-in made through a registered app can be traded. The sign-in names your app when your app sends its client id as client in the e-mail-code sign-in, POST https://id.gilb.com/base/auth/email/verify-code; in a browser, on an origin the platform owner approved for your app, the origin names it. The service must list your app, and your app's registration must still be live; otherwise the trade answers 403 unauthorized_client.
A token from a browser session is refused: the DPoP-bound one names no app (403 unauthorized_client), and the plain one is bound to no key (400 invalid_grant). A person with no vault yet is refused too: 400 invalid_grant, this person has no WebID yet: create a vault first. A WebID here is the person's vault address, such as https://<name>.gilb.com/vault.
Other refusals have the same two fields, error and error_description. 400 invalid_grant: the sign-in token is not valid or has run out, the proof is signed by another key, or the person has signed out. 400 invalid_scope: an action the service does not have. 400 invalid_request: a missing, bad or reused DPoP proof. 503 temporarily_unavailable: the platform could not read what it needs; try again. A form with a missing or unknown field, such as client_secret, is refused with 400 before these checks; that answer has error and message, not error_description.
When the person signs out, the platform makes no new service token for that sign-in, but a service token already given keeps working at the service until it runs out, at most 300 seconds. Not there today: an outside service acting for the person in their vault, and a screen to register or manage outside services.
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/outside-service-exchange.ts:61, :64 (grant and token types), :149-160 (required fields), :169-171 (only a person's sign-in token), :172-177 (no cnf.jkt: invalid_grant), :178-181 (no azp: unauthorized_client), :189-191 (expired), :195-208 (proof signed by the bound key), :221-234 (signed out: invalid_grant), :247-252 (invalid_target), :260-265 and :271-288 (app on the list, registration live: unauthorized_client), :298 and :400-417 (scope), :304-316 (this person has no WebID yet: create a vault first), :367-382 (expires_in = min(300, remaining); aud = service address; azp = app; token_type DPoP; no refresh token); src/routes/machine-token.ts:48-84 (form fields, additionalProperties false; such a refusal goes through src/server/app.ts:244-256, body error and message), :95-100 (403/503/400), :163-205 (POST /base/oauth/token, error and error_description); src/routes/outside-service-lookup.ts:3-8, :17-20 (pin the origin, refuse redirects, use only the signed address), :42 and :70-72 (400 bad service id), :47-51 (24 h, cache 300 s), :92-95 (404 not found for missing, suspended, withdrawn), :98-115 (typ outside-service+jwt, application/jwt); src/auth/outside-service-registry.ts:1-9 (no HTTP route; owner's CLI only); src/routes/email-auth.ts:92-121 (client field), :502-509 (marker from the approved origin, else body client); src/auth/email-otc.ts:457-463 (client stamped as azp); src/routes/session-token.ts:450-473 (browser-session DPoP token minted with no client); src/auth/issue.ts:83 (azp only when client given), :112-130 (plain session Bearer has no cnf.jkt); src/auth/verify.ts:221-251 (each trusted issuer pins its own audience: no vault access). REAL on production per the GilbPlatform handoff of 2026-11-10 (proofs P1-P8): 300 s, sub the vault address, aud, azp, iss https://id.gilb.com/base/auth, resource-as-address 400 invalid_target, exchange after sign-out 400 invalid_grant. Public reads 2026-11-11: https://id.gilb.com/base/auth/jwks.json 200 (one EC P-256 ES256 key, cache-control public, max-age=300); https://id.gilb.com/base/service/zzzzzzzzzzzzzzzzzzzzzzzzzz 404 {error:not found}, no-store. Dev.Guide.OutsideServices (A 06gwd3evv9s9zaba5fx0d43ybc, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied).
For developers
curl
lookup.sh
# Look up an outside service. No token is needed.
curl -s https://id.gilb.com/base/service/<service id>
TypeScript
service-address.ts
import { createRemoteJWKSet, jwtVerify } from "jose";
const PLATFORM = "https://id.gilb.com";
const keys = createRemoteJWKSet(new URL(`${PLATFORM}/base/auth/jwks.json`));
// The one address your app may send a person's service token to.
export async function serviceAddress(serviceId: string): Promise<string> {
const res = await fetch(`${PLATFORM}/base/service/${encodeURIComponent(serviceId)}`, { redirect: "error" });
if (res.status !== 200) throw new Error(`service lookup answered ${res.status}`);
const { payload } = await jwtVerify(await res.text(), keys, {
algorithms: ["ES256"],
typ: "outside-service+jwt",
issuer: `${PLATFORM}/base/auth`,
});
const service = payload.service as { id: string; address: string; actions: string[] };
if (service.id !== serviceId) throw new Error("the answer names another service");
return service.address;
}
curl
exchange.sh
# Trade the person's sign-in token for a service token (RFC 8693).
# The DPoP proof is new for this request, signed with the key the sign-in token is bound to.
curl -s https://id.gilb.com/base/oauth/token \
-H "DPoP: <a new proof for POST https://id.gilb.com/base/oauth/token>" \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
--data-urlencode "subject_token=<sign-in token>" \
--data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
--data-urlencode "resource=<service id>"
# 200: {"access_token":"<service token>","issued_token_type":"urn:ietf:params:oauth:token-type:access_token",
# "token_type":"DPoP","expires_in":300,"scope":"<the actions granted>"}
Checked against GilbApp d529620.