API Overview
Auth mechanisms and route-group map.
The Rensei platform exposes a structured REST API surface organized into distinct route groups, each with a consistent authentication model. This page maps every group, its auth mechanism, and where to find the detailed reference.
Route group map
| Group | Prefix | Auth mechanism | Audience |
|---|---|---|---|
| Public stats & sessions | /api/public/* | Cookie session or Bearer rsk_* (per-session routes also accept the session hash) | Chat consumers, monitoring dashboards |
| Browser/CLI user | /api/org/*, /api/projects/*, /api/workflows/* | Cookie session or Bearer rsk_live_* | Dashboard users, CLI operators |
| Worker protocol (pre-v1) | /api/workers/*, /api/sessions/* | Bearer <runtime_jwt> (preferred), registration token, or legacy opaque key (deprecated) | Self-hosted daemon, donmai CLI |
| Worker protocol v1 (daemon-native) | /v1/daemon/register, /v1/daemon/heartbeat | Registration token in body (register) / Bearer <runtime_jwt> (heartbeat) | rensei-tui daemon |
| OAuth / Token | /api/oauth/token | client_credentials grant | M2M SDK clients, CI/CD pipelines |
| Webhook ingest | /api/webhooks/ingest/[provider] | HMAC signature per provider | Linear, GitHub, Vercel, GitHub Actions |
| A2A protocol | /api/a2a/* | Cookie/bearer | Workflow editor users, peer agents |
| MCP tool endpoint | /api/mcp/[sessionId] | Bearer rsk_* | Daemon/agent subprocesses |
| Audit log | /api/audit/* | Cookie/bearer; anchor/verify accept M2M JWT | Operator admins, auditors, SIEM |
| Discovery | /.well-known/agent-card.json, /.well-known/audit-keys/[workspace_id] | None (public) | A2A peers, external auditors |
| SCIM provisioning | /api/scim/webhook | SCIM bearer token | IdP (Okta, Azure AD) |
| Admin (system) | /api/admin/* | scope='system' session or API key | Operator admins |
| Health | /api/health | None (public) | Load balancers, status pages |
The /api/org/* handlers use requireOrgAccess(), which is cookie-only. CLI clients that authenticate with a Bearer rsk_* key must use sub-paths that call getCliOrSessionAuth (e.g. /api/org/[orgId]/keys). See API Key Authentication for detail.
Authentication at a glance
Rensei uses three main authentication models depending on who is calling:
API Keys (rsk_)
Long-lived bearer tokens for CLI operators, daemon workers, and programmatic integrations. Format: rsk_live_*.
M2M OAuth
Short-lived access tokens for machine-to-machine scenarios - CI/CD pipelines and external services. Uses OAuth 2.0 client_credentials.
Worker Runtime JWT
Per-worker signed JWT issued at registration. Required for all worker loop endpoints (/api/workers/[id]/poll, session lifecycle, etc.).
API reference sections
Worker Protocol
Registration, heartbeat, poll, session lifecycle, file reservation, and credential snapshot. The self-hoster reference.
Public Sessions API
No-auth stats and session endpoints for chat consumers and monitoring tools.
A2A Protocol
Agent discovery via .well-known/agent-card.json and agent dispatch management.
MCP Tool Endpoint
JSON-RPC 2.0 tool surface for agent subprocesses.
Webhook Ingest
HMAC-verified ingest gateway for Linear, GitHub, Vercel, and GitHub Actions.
Audit API
Hash-chain audit log, Merkle anchoring, SIEM export, and crypto-shredding.
Base URL
All production API endpoints are served from https://app.rensei.ai. Example:
curl -s https://app.rensei.ai/api/healthCommon request headers
| Header | Required | Example |
|---|---|---|
Authorization | Yes (auth'd routes) | Bearer rsk_live_abc123 |
Content-Type | Yes (POST/PATCH) | application/json |
Accept | Optional | application/json |
Error responses
All API errors return JSON with error and optional message fields:
{
"error": "Unauthorized",
"message": "Missing or invalid bearer token"
}Standard HTTP status codes apply: 400 for validation errors, 401 for missing auth, 403 for insufficient permissions, 404 for not found, 500 for internal errors.
Self-hosting
The full worker-protocol API surface - registration, poll, heartbeat, session lifecycle, credentials - can be hosted independently using the @donmai/nextjs package. It provides pre-built Next.js App Router route handlers that implement the same contracts as the Rensei hosted platform. The donmai daemon connects to a self-hosted backend without any configuration changes.
pnpm add @donmai/nextjs @donmai/core @donmai/serverSee TypeScript SDK for the package catalogue and quick-start guide.