← Connecting other services (e-mail, maps, calendars, files, other services)
How do I get an outside service registered?
Short answer
Send the platform owner your https address, action names, the allowed apps' client ids and a contact e-mail, then give each app the service id.
Before you start
The apps that will use your service are registered with GilbPlatform, and you have their client ids.
Words used here (4)
- 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.
- 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.
- GilbPlatform
- GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
- 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.
Steps
Decide your service's https address.
Pick the one https address apps will send the service token to; every token for your service carries it, exactly, as its audience (aud).
More about this
It is one https:// address, such as https://<your service's host>, with an optional path. Not allowed: *, a query, a fragment, a user name or password, a . or .. segment, // in the path, %2e or %2f, a percent-encoded letter, digit or one of - . _ ~, or a host ending in a dot. A trailing / and the default port are dropped. It must not be a host GilbPlatform serves itself, such as a vault's host. One address is one service: an address another service already has is refused, unless that service was withdrawn.
List your service's action names.
Write the names of the things an app may ask your service to do, such as photo:edit; a token carries, in its scope, the ones the app asked for, or all of them if it asked for none.
More about this
1 to 32 names. Each starts with a lower-case letter, followed by up to 63 lower-case letters, digits or the signs . _ : -, and no name comes twice. base.read and base.write are kept for the platform. The platform keeps the names sorted and never reads meaning into them; they grant nothing in any vault, and your service decides what each one allows.
List the client ids of the apps allowed to use it.
Name each app by its client id, the name the platform gave the app when it was registered; each app must already be registered.
More about this
The owner cannot add a client id that has no live registration. Only a sign-in made through one of these apps can be traded for a token for your service; a sign-in through any other app is refused.
Send the four things to the platform owner.
Send the platform owner, who runs GilbPlatform, the address, the action names, the client ids and an e-mail address the owner can reach you at. Only the platform owner can register a service: there is no screen and no HTTP route for it.
More about this
The contact e-mail is for the owner. The public lookup of your service shows only its id, address and action names, not the apps or the e-mail.
Give the service id to each app.
The owner sends back your service id, 26 lower-case letters and digits; give it to every app on your list.
More about this
An app looks your service up by it and names it as the resource when it trades a person's sign-in token for a service token. Once your service is registered, this lookup answers 200 with a signed answer:
GET https://id.gilb.com/base/service/<service id>
Deeper
Also asked:
How do I get an outside service approved for my app? Only the platform owner, who runs GilbPlatform, can register one: send the owner the service's https address, its action names, your app's client id and a contact e-mail. There is no screen for it.
How do I get my own outside service registered? Send the platform owner its https address, its action names, the client ids of the apps allowed to use it and an e-mail address. The owner sends back a service id; give it to each app.
Later, the owner can change the address, the action names, the apps or the contact; what is not changed stays as it was, and a new list replaces the old one. The owner can also suspend a service and resume it, or withdraw it. A suspended or withdrawn service gets no new tokens, and its lookup answers 404 not found, the same as a service that was never registered. A withdrawn service cannot be resumed; registering it again gives it a new service id. Tokens already given keep working at your service until they run out, at most 300 seconds.
Registering lets apps trade a person's sign-in for a token your service can check; it gives your service no access to anyone's vault. 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-registry.ts:1-9 (no HTTP route; only the owner's CLI writes a registration), :33-52 (address, actions, allowed clients, state active|suspended, contact a:email), :59 (base.read, base.write reserved), :100-205 (canonicalServiceAddress: the rules in step 1; :208-224 unreserved percent-encoding), :225-265 (platformHostRefusal: hosts the platform serves, the vault domain), :276-303 (validateActions: 1-32, regex, reserved, no duplicates, sorted), :304-341 (registerOutsideService: random new id, allowed clients must have a live registration, address must be free), :343-390 (update: omitted fields stay, a given list replaces), :392-430 (suspend/resume), :447 (withdraw ends the record), :616 (assertAddressFree), :625 (assertAllowedClients), :637 (assertContactEmail); src/routes/outside-service-lookup.ts:24-27 (public; shows address and action names, not clients or contact), :92-95 (one 404 for missing, suspended, withdrawn), :98-115 (200 signed); src/auth/outside-service-exchange.ts:247-252 (not active: no token), :260-265 (app not on the list: refused), :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). REAL on production per the GilbPlatform handoff of 2026-11-10: a withdrawn service's lookup answered 404, the same as an unknown one; 300-second tokens. Public read 2026-11-11: https://id.gilb.com/base/service/zzzzzzzzzzzzzzzzzzzzzzzzzz 404 {error:not found}. Dev.Guide.OutsideServices (A 06gwd3evv9s9zaba5fx0d43ybc, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) Register (The owner gives you back the service id). The owner's command is not shown (handoff 2.3).
Checked against GilbApp d529620.