Adding New API Endpoints

Authenticated is not scoped. requireAuth proves who the caller is and nothing about what they may reach. Platypus is multi-tenant — Organization → Workspace → resource — so an endpoint carrying only requireAuth is reachable by any logged-in user against any tenant's data. Scope is a separate, mandatory decision, taken per route.

Steps

1. Create the route module in the backend's routes area — a Hono instance exported for mounting.

2. Mount it on the app in the backend's server module. The mount path carries the tenancy, so the hierarchy lives in the URL and the middleware reads the ids from it:

   app.route("/organizations/:orgId/workspaces/:workspaceId/agents", agent);

3. Define the request schemas in the shared schemas package, following the full / create / update variants each domain model already has.

4. Compose each route: authenticate, scope, validate, handle — in that order, as arguments to the route, not as a blanket .use("*"). Scope is per route because two routes in one file rarely deserve the same access.

   agent.post(
     "/",
     requireAuth,
     requireOrgAccess(),
     requireWorkspaceAccess,
     validate("json", agentCreateSchema),
     async (c) => {
       const data = c.req.valid("json");
       const scope = workspaceScopeOf(c);
       // ...
     },
   );

Done when every route in the module names its scoping middleware explicitly, and you can say which tenant each one is confined to.

Choosing the scope

Pick the narrowest that admits the callers you intend:

Org and Workspace scoping compose — the Workspace check assumes the Org check ran ahead of it. Super admins bypass the Org membership check by design, so a route may legitimately resolve with no Organization to scope to.

Read the resolved scope through the scope accessors (workspaceScopeOf, orgScopeOf) rather than re-reading path params: the accessor hands you the scope the middleware already decided, so the query cannot disagree with the authorization. Likewise read the session user and Org membership through userOf and orgMembershipOf, never c.get("user")!: they throw (a 500) when the middleware is missing from the route.

Database access

Import the shared db instance from the backend entry module, the way the route modules already do, and query it with Drizzle. The request context also carries a db, but that is a narrow exception rather than the house pattern.

Never scope a query by a raw path param. Take the tenant ids from the resolved scope, so an unscoped read cannot be written by accident.

Responses

Response body shape — the error key, the message key, and when to throw a typed error instead of returning one — is covered by the api-conventions skill. Load it rather than inventing a shape.