API reference

The application serves its generated API reference at /api-docs. That page reads the OpenAPI document at /openapi.json. Route definitions and their annotations live in app/api/; the docs:generate package script runs next-openapi-gen generate. Use the generated reference for paths, methods, request shapes and responses.

Browser requestsCopy Anchor Link

When you sign in through the web interface, NextAuth.js manages a browser session. Browser-facing API handlers use that session to identify you and then check your access to the requested case or resource. The sign-in configuration supports email and password, GitHub and Google. You do not create a session cookie by hand.

Machine requestsCopy Anchor Link

An integration calls the /api/machine surface with an Authorization: Bearer teap_… header. The secret is issued for an integration and is checked against the stored token record on each request. Its scopes limit the operations it may perform. Access to individual cases also follows the integration's case grants; a scope alone is not a case grant. The current scope vocabulary is case:read, health:checks:write, health:criteria:read, health:evidence:read and health:evidence:write.

Create and revoke integration tokens through the authenticated integration controls. Keep the full token secret when it is issued, since later views expose only a prefix. Use the generated API reference for the supported machine routes.