Developers
CentraKit REST API base URLs, authentication model, generated client, and current public route coverage.
The CentraKit API app exposes REST endpoints under /api/v1 and the MCP server under /api/mcp.
https://api.centrakit.com/apihttps://api.localhost/apihttp://localhost:3001/apiAPI handlers create request-scoped services through the API boundary. They support browser session cookies and bearer tokens, which keeps the same API usable by browser flows, the CLI, and MCP clients.
Use a bearer token for headless scripts, CLI calls, and MCP hosts:
centrakit --token <access-token> organizations listwithApiRoute({ policy: "user" }) authenticates the request boundary; it does not authorize
access to an organization from a path parameter. Every documented organization route must
also enforce the matching existing permission before its first domain read or write:
apps/api/lib/organization-route-permissions.ts and performs an authoritative organization
check before invoking the handler.authorizeOrgScope or withOrgPermission are marked as
handler-authorized in that registry so the adapter does not repeat the check.view for reads and the existing operation-specific create, update, delete, or
lifecycle permission for mutations. Do not invent a permission at the route boundary.tests/integration/api/organization-route-authorization.test.ts enumerates every
@openapi handler below /api/v1/organizations/[organizationId] and fails when an operation
has neither an adapter mapping nor a verified handler-owned gate.
RLS remains mandatory defense in depth and constrains the rows a provider can access, but it does not replace the route gate. The explicit check gives cookie and bearer clients the same 401/403 contract, prevents accidental authorization through a provider change, and avoids using an empty RLS result as an authorization decision.
Anonymous token routes authorize through their token contract instead. Purpose-specific internal cron, webhook, SSE, and worker transports keep their own boundary checks and are not public organization CRUD routes.
Current API routes include:
/api/mcp.Generated OpenAPI pages are available from the OpenAPI Reference.
The typed API client is generated from the committed OpenAPI spec into packages/api-client with Hey API. The generated client includes SDK functions, TypeScript types, and Zod validators. Its @workspace/api-client/mcp subpath owns the MCP allowlist, operation metadata, generated input validation, and typed REST executor. Keep route schemas and operation IDs stable for public API consumers.