Skip to content

Endpoint security

Pages and external endpoints are reachable from the internet. The rules are simple:

  • Pages are public. A page’s HTML and static files load without authorization.
  • Everything else is protected, also routes that only read data, unless you decide otherwise.
  • Your application’s own Adapt credentials never authorize an incoming request.
  • Authorization stays on, also during development and in the emulator.

Browser pages get a token from Adapt. Protect the routes that they call with useBearerAuthorization:

executor.ts (excerpt)
export const external_http = createEERouter((router) => {
// Every /api route needs the page's token. The page itself stays public.
router.useBearerAuthorization(["/api"]);
router.addRoute("POST", "/api/cancel", async (request, api) => {
const session = api.getSessionApi(request.headers.get("Authorization") ?? "");
await session.send("cancelled");
return new Response(null, { status: 204 });
});
});

The middleware checks the token with Adapt before the route runs. It answers 401 without a token, and 403 with an invalid one. Then use api.getSessionApi() with the request’s Authorization header to send outputs.

  • The paths are prefixes of whole path segments, such as /api. Without paths, every route is protected.
  • An optional second list exempts paths. Never exempt / or "": that turns authorization off for everything.
  • Settings pages have their own token, and executor routes reject it.

Webhooks get no token from Adapt. Verify them with the provider’s method instead, usually a signature, before you read or change anything. Keep webhook routes outside the paths that useBearerAuthorization protects.

A webhook belongs to one session, but the provider cannot send you that session’s token. Save it when the vertex starts:

  1. In onStart, save api.getAuthHeader() in the vertex’s store, under the provider’s ID for the request.
  2. When the webhook arrives, verify it, then look up the saved header.
  3. Use the header with api.getSessionApi(), and remove the entry when the session ends.
executor.ts (excerpt)
type Callback = { auth: string };
export const internal_http = createIERouter((router) => {
router.onStart(async (request, api) => {
const payment = await createPayment(`https://${request.host?.publicHost}/webhook`);
await api
.getLocalStore("vertex")
.insert<Callback>(`callback/${payment.id}`, { auth: api.getAuthHeader() }, 3600);
});
});
export const external_http = createEERouter((router) => {
router.useBearerAuthorization(["/api"]); // The webhook stays outside these paths.
router.addRoute("POST", "/webhook", async (request, api) => {
const body = await request.text();
if (!(await verifySignature(body, request.headers.get("X-Signature")))) {
return new Response(null, { status: 401 });
}
const event = JSON.parse(body) as { paymentId: string };
const store = api.getLocalStore("vertex");
const entry = await store.get<Callback>(`callback/${event.paymentId}`);
if (!entry) return new Response(null, { status: 404 });
await api.getSessionApi(entry.data.auth).send("paid", { paymentId: event.paymentId });
await store.delete(`callback/${event.paymentId}`);
return new Response(null, { status: 204 });
});
});

Here, createPayment and verifySignature stand for your provider’s API and its verification library. Never put the session’s token in a callback URL, and never use one session’s token for another.

TCP and datagram handlers do not use the HTTP middleware. Check the caller in each handler.

  • Keep credentials in services, never in code, settings, pages, logs, or error messages.
  • Your logs belong to the people who install your application. Log what helps them, without credentials or sensitive data.
  • Adapt records all input and output of your application, and its users can see these records. Use each service only for the purpose that your README describes.

Before you release, list each endpoint with its rules, and check that the code enforces them:

Endpoint Caller and authorization Input Output Side effects
GET / Anyone None The page’s HTML. No data. None
GET /api/slots The page, with its token A date range of at most 62 days Free times only Reads the calendar
POST /api/book The page, with its token Validated JSON, at most 20,000 characters The visitor’s own booking Creates an event, sends booked

Coding agents with the adapt-app skill do this audit for each endpoint. Its endpoint-security.md reference has the full checklist. Ask for the result in your developer notes.

For each endpoint, test:

  • the callers that may call it,
  • missing, invalid, and expired tokens, and tokens from another session or page,
  • for webhooks: invalid signatures, unknown IDs, duplicates, and calls after the session ended,
  • malformed and oversized input.

Rejected requests must return no protected data, and change nothing. Test your logic with unit tests, and the real tokens in the emulator.