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.
Protect your API
Section titled “Protect your API”Browser pages get a token from Adapt. Protect the routes that they call with useBearerAuthorization:
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 and other external callers
Section titled “Webhooks and other external callers”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:
- In
onStart, saveapi.getAuthHeader()in the vertex’s store, under the provider’s ID for the request. - When the webhook arrives, verify it, then look up the saved header.
- Use the header with
api.getSessionApi(), and remove the entry when the session ends.
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.
Secrets and logs
Section titled “Secrets and logs”- 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.
The endpoint security audit
Section titled “The endpoint security audit”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.
Test the boundaries
Section titled “Test the boundaries”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.