Authentication
Three authentication schemes are in play across the REST surface:
| Scheme | Header / cookie | Used by |
|---|---|---|
| sessionCookie | Authorization: <token> or Cookie: session-token=<token> | /dashboard/*, /report/*, /user/* (authenticated routes) |
| robotBearer | Authorization: Bearer crat-… | /robot/* |
| (none) | — | /cloud/*, /user/login*, /user/password/* |
The same session token works for the GraphQL endpoint — both APIs share the authorization middleware.
Editing the spec
Every operation under /user/*, /robot/*, /cloud/*, /dashboard/*, and /report/* carries a @openapi JSDoc block. Adding a new endpoint? Annotate the handler and the next deploy regenerates this page. Run yarn docs:graphql locally to refresh the spec; it pulls the JSDoc, prints it as docs/public/openapi.json, and the viewer above picks it up at runtime.