HTTP API & platform contracts
Complete authenticated Worker endpoints, concurrency headers, normalized entity synchronization, execution Flight Recorder routes, and error envelopes.
Authentication and required headers
All /api/v1/* routes require an authenticated principal. In production (ENVIRONMENT=production), the Worker enforces AUTH_MODE=oidc and verifies JWT signatures against configured OIDC_ISSUER, OIDC_AUDIENCE, and JWKS keys. Local header authentication is rejected outside ENVIRONMENT=local.
| Header | Required on | Contract behavior |
|---|---|---|
Authorization: Bearer <jwt> | All /api/v1/* requests | Resolves immutable OIDC subject and enforces tenant RBAC (owner, admin, member, auditor). |
Idempotency-Key | All mutating requests (POST, PUT, DELETE) | Stores canonical response keyed by tenant, route, key, and SHA-256 payload hash. Reusing a key with a different payload returns 409. |
If-Match | Versioned workspace updates | Requires the last observed integer version. Stale versions fail with 409 version_conflict without writing audit entries. |
x-request-id | Returned on every response | Correlates HTTP responses, structured Worker logs, audit records, and Flight Recorder spans. |
Idempotency and optimistic concurrency
- Every mutating call reserves an idempotency slot before mutating D1 state and replays the exact stored status and canonical JSON on safe retries.
- JSON request payloads above
1.5 MBare rejected before parsing; outbound connector responses are capped at256 KB. - Non-members probing a foreign
:tenantIdreceive404 not_foundrather than403so tenant identifiers cannot be enumerated. - Audit records and execution lifecycle events are strictly append-only and cryptographically hash-chained.
Health, tenant, and workspace endpoints
| Method | Path | Role | Summary |
|---|---|---|---|
| GET | /api/health/live | Public | Confirms Worker process liveness. |
| GET | /api/health/ready | Public | Verifies D1 schema readiness, OIDC config, HTTPS origin allowlist, and Queue bindings. |
| GET | /api/v1/tenants | Authenticated | Lists tenants where the caller holds an active membership. |
| POST | /api/v1/tenants | Authenticated | Creates a tenant, owner membership, initial workspace snapshot, and genesis audit event. |
| GET | /api/v1/tenants/:tenantId/workspace | auditor+ | Returns current workspace snapshot, version, and ETag. |
| PUT | /api/v1/tenants/:tenantId/workspace | member+ | Updates workspace state when If-Match matches current version. |
| GET | /api/v1/tenants/:tenantId/audit | auditor+ | Lists ordered, hash-chained tenant audit events. |
Normalized entities and cursor delta feed
GET /api/v1/tenants/tnt_northstar/changes?after=42&limit=250 HTTP/1.1
Host: frootai.io
Authorization: Bearer <oidc-jwt> {
"changes": [
{
"cursor": 43,
"entityType": "work_item",
"entityId": "WRK-104",
"version": 3,
"operation": "upsert",
"actorUserId": "usr_01",
"traceId": "trc_9fa21c",
"dataHash": "sha256:8f9c...",
"updatedAt": "2026-11-16T09:30:00.000Z"
}
],
"nextCursor": 43,
"hasMore": false
} GET /api/v1/tenants/:tenantId/entities/:entityType
POST /api/v1/tenants/:tenantId/entities/:entityType
GET /api/v1/tenants/:tenantId/entities/:entityType/:entityId
PUT /api/v1/tenants/:tenantId/entities/:entityType/:entityId
DELETE /api/v1/tenants/:tenantId/entities/:entityType/:entityId
Clients persist nextCursor locally and advance monotonically until hasMore is false. Current browser clients poll once per second while active.
Work executions, Flight Recorder, and replay
POST /api/v1/tenants/:tenantId/work/:workId/executions
GET /api/v1/tenants/:tenantId/work/:workId/executions
GET /api/v1/tenants/:tenantId/jobs/:jobId
GET /api/v1/tenants/:tenantId/jobs/:jobId/events
POST /api/v1/tenants/:tenantId/jobs/:jobId/cancel
POST /api/v1/tenants/:tenantId/jobs/:jobId/replay Admission commits the job and transactional outbox row in D1 before publishing to Cloudflare Queues, enforcing at most one active attempt per work item and tenant concurrency caps. See Execution Flight Recorder & replay for event phases and cancellation guarantees.
Extension and secret-reference transitions
GET /api/v1/tenants/:tenantId/connectors
POST /api/v1/tenants/:tenantId/connectors
GET /api/v1/tenants/:tenantId/extensions
POST /api/v1/tenants/:tenantId/extensions
POST /api/v1/tenants/:tenantId/extensions/:extensionId/transition
GET /api/v1/tenants/:tenantId/secret-references
POST /api/v1/tenants/:tenantId/secret-references
POST /api/v1/tenants/:tenantId/secret-references/:secretReferenceId/transition Secret-reference routes accept only binding aliases, provider types, and non-secret metadata. Any payload containing raw secret keys or token strings is rejected at schema validation.
Canonical error envelope and status codes
{
"error": {
"code": "version_conflict",
"message": "Workspace version does not match If-Match header.",
"traceId": "req_01jcv92k8m"
}
} | Status | Error code | When returned & client action |
|---|---|---|
400 | validation_error / missing_idempotency_key | Malformed schema or missing required headers. Fix request contract before retrying. |
401 | unauthenticated | Missing, expired, or invalid OIDC bearer token. Refresh authentication. |
403 | insufficient_role | Caller is a tenant member without required role (for example, auditor attempting a write). |
404 | not_found | Resource does not exist or caller is outside the tenant boundary. |
409 | version_conflict / idempotency_conflict / work_execution_active | Reload latest state or use a fresh idempotency key for a distinct mutation. |
429 | tenant_execution_capacity_exceeded | Tenant has reached its concurrent active execution limit (default 4). Wait for active runs to finish. |
tests/backend/api.test.tstests/backend/repository.test.tstests/backend/platform.test.tstests/backend/jobs.test.ts