Adding your own API

Orb fronts HTTP APIs. JSON responses work best, because agents read them easily.

1. Make it reachable

Your service must answer on 127.0.0.1:<port>. The sync script rejects any other upstream, so a remote API needs a local proxy in front of it. Start with a plain HTTP API; check that its auth fits the modes below before adding anything that streams responses or needs a handshake of its own.

2. Declare it

Add it to services.json like any other source, with a name, a path, and its loopback upstream. See Getting started. name is also the scope prefix.

3. Scope a key to it and test

Add <name>:read to a key in the admin, then request the service through the gateway and check the response. A key without the scope gets 403.

4. Write its info page

Info pages do not discover endpoints. Add an entry to data/api-docs.json with the API’s name, lane, base path, scope, endpoints, example and any notes, then check the page at /apis/<name> and confirm the copied brief is right. bin/orb.mjs also shows an endpoint count when the upstream serves a real OpenAPI document.

Upstream auth

Two modes cover most services:

• {"mode": "strip"}: the service needs no key. Orb removes the caller’s Authorization header.
• {"mode": "swap_key", "env": "MY_KEY"}: Orb sends its own Bearer key, read from MY_KEY in the gateway’s .env.

Add "per_token": true to a swap_key service to let a caller’s own key travel with its token. You attach that key per token with bin/set-upstream-key.sh. Callers cannot set it themselves; Caddy drops any X-Upstream-Auth header they send. An optional upstream_prefix pins the service to one subtree of the upstream API.

Keep upstream credentials on your machine. The gateway key is what agents see.