API Gating & Engine Reference
Every request to https://api.nunc.cloud is gated by origin policy, credential prefix, and application principal type before reaching tenant storage or connectors. Backend service connections cannot read Nunc UI routes, API keys cannot invoke Tenant Admin endpoints, and browser embeds never hold tenant keys.
https://api.nunc.cloudLooking for backend-to-backend SaaS/SQL connector execution? See the dedicated Service Connections API (/service) guide. Building a custom TypeScript app or portal? Use @nunc/sdk & Web Embed.
1. How Nunc gates Nunc-only APIs vs. external connections
The gateway enforces five independent security boundaries on every request:
- Browser CORS & CORP isolation: Browser cross-origin requests to
/api/*and/chat/*are restricted to first-party Nunc origins (nunc.cloud,studio.nunc.cloud,console.nunc.cloud,admin.nunc.cloud) withCross-Origin-Resource-Policy: same-origin. External web origins cannot call/api/*from a browser. - Tenant Admin control-plane lock (human SSO JWT only): Every administrative route — registering applications (
/api/applications*), installing connectors, editing PBAC or Guardian policies (/api/governance/*), and managing organization members (/api/tenants*) — rejects everynunc_*API key with403 Tenant admin role required. Only a human Console SSO JWT carrying theadminorownerrole is accepted. - Application type gating (
servicevs.chatvs.federated): Non-humannunc_*keys are bound to anapp_<hex>principal whosetypestrictly restricts which surfaces accept it:type="service"— Admitted on POST /service (and headless/mcpconnector calls). Hard-blocked (403) on all/api/*routes,/chat/completions,/mcp/memory,/mcp/analytics, and/mcp/sandbox.type="chat"— Admitted onPOST /chat/completionsand non-admin/api/*engine routes for @nunc/sdk. Hard-blocked (403) on/serviceand/mcp*.type="federated"— Admitted on/mcp(Guardian-scanned MCP tool federation) and non-admin/api/*routes. Hard-blocked (403) on/chat/completionsand/service.
- Human-only MCP surfaces & OAuth 2.1 audience binding:
/mcp/analytics,/mcp/memory, and/mcp/sandboxreject all Application principals (403) and require an interactive human OAuth 2.1 PKCE token bound to that exact resource URL (RFC 8707). - Ephemeral Web Embed sessions (
nes_*): Published widgets (/embed.js,/e/:slug) exchange a host-signed identity JWT atPOST /e/:slug/sessionfor a 24-hourBearer nes_<hex>token (ext:<appId>:<sub>) accepted only onPOST /chat/completionsand locked to configuredallowed_originsvia CSPframe-ancestors.
2. Principal & surface access matrix
| Credential / Principal | Console Admin (/api/applications, /api/governance) | Engine REST (/api/workflows, /api/sandbox, /api/memory) | Chat SSE (/chat/completions) | MCP (/mcp*) | Service (/service) |
|---|---|---|---|---|---|
| Nunc Admin (First-Party SSO JWT) | Allowed | Allowed | Allowed | Via OAuth 2.1 | Denied (403) |
| Nunc Member / Viewer (SSO JWT) | Denied (403) | Allowed (viewer read-only) | Allowed | Via OAuth 2.1 | Denied (403) |
| Human OAuth 2.1 PKCE Token | Denied (401) | Denied (401) | Denied (401) | Allowed (all 5 /mcp*) | Denied (403) |
Service App Key (nunc_*, type="service") | Denied (403) | Denied (403) | Denied (403) | /mcp tools only (403 elsewhere) | Allowed |
Chat App Key (nunc_*, type="chat") | Denied (403) | Allowed (scoped) | Allowed (+ X-Nunc-External-User) | Denied (401) | Denied (403) |
Federated App Key (nunc_*, type="federated") | Denied (403) | Allowed (scoped) | Denied (403) | Allowed (/mcp) | Denied (403) |
Embed Session (nes_*, 24h TTL) | Denied (401) | Denied (401) | Allowed (ext:<appId>:<sub>) | Denied (401) | Denied (401) |
3. Governed SSE chat streaming (POST /chat/completions)
Server-side applications registered with type="chat" can stream governed completions over Server-Sent Events. Pass X-Nunc-External-User: <sub> (matching /^[A-Za-z0-9._:@|-]{1,128}$/) to scope conversation threads, memory, and per-user rate limits to ext:app_<hex>:<sub>. The accepted response returns X-Nunc-Thread-Id with the gateway-assigned conversation ID:
curl -N -X POST https://api.nunc.cloud/chat/completions \
-H "Authorization: Bearer $NUNC_CHAT_APP_KEY" \
-H "X-Nunc-External-User: usr_94810" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"messages": [
{ "role": "user", "content": "Compare Q3 vs Q2 net retention by segment." }
],
"mode": "work",
"stream": true
}'Named SSE frames (event: tool_call, event: tool_result) carry structured governance telemetry, while unnamed data: frames emit OpenAI-compatible assistant token deltas:
event: tool_call
data: {"name":"nunc_analytics_query","args":{"query":"{ arrRetention(quarter: \"Q3\") { segment netRetention } }"}}
event: tool_result
data: {"name":"nunc_analytics_query","status":"ok","rows":4}
data: {"choices":[{"delta":{"content":"Enterprise net retention rose to 114.2% in Q3..."}}]}
data: [DONE]4. Engine REST & JSON-RPC endpoint reference
Nunc exposes flat, unversioned paths on https://api.nunc.cloud (there is no /v1/ prefix).
| Domain | Routes | Accepted Credentials |
|---|---|---|
| Service Data Plane | POST /service GET /service/health | Bearer nunc_* bound to type="service" Application only. See /docs/service-api. |
| Chat & Approvals | POST /chat/completions POST /chat/resume GET /chats · GET /chats/:id | SSO JWT, type="chat" Application key, or Bearer nes_* embed token (completions only). |
| Published Web Embed | GET /embed.js · GET /e/:slug POST /e/:slug/session | Host-signed HMAC identity JWT exchanged for a 24h nes_* token, gated by external_surfaces and CSP frame-ancestors. |
| Workflows & Runs | POST /api/workflows/runs · GET /api/workflows/runs/:id POST /api/workflows/runs/:id/steps/:stepId/approve GET /api/saved-workflows · POST /api/saved-workflows/:id/run | SSO JWT or non-service nunc_* Application key (chat / federated). |
| Isolated Code Sandbox | POST /api/sandbox/execute · POST /api/sandbox/eval POST /api/sandbox/stage · GET /api/sandbox/stage GET /api/sandbox/status | SSO JWT or non-service nunc_* Application key. |
| Memory & Knowledge | POST /api/memory/search · POST /api/memory/ingest POST /api/knowledge/ingest · GET /api/sources | SSO JWT or non-service nunc_* Application key (scoped to permitted workspaces/agents). |
| Applications & Audit Admin | GET/POST /api/applications · POST /api/applications/:id/keys GET /api/governance/audit/logs GET /api/governance/audit/export | Human Tenant Admin SSO JWT only (all nunc_* keys rejected with 403). |
Trigger a workflow run via REST
curl -sS -X POST https://api.nunc.cloud/api/workflows/runs \
-H "Authorization: Bearer $NUNC_CHAT_APP_KEY" \
-H "Content-Type: application/json" \
-d '{
"scope": "Reconcile overdue Q3 invoices and queue dunning drafts for approval"
}'5. Tenant surface kill switches & HTTP status codes
Tenant Administrators can disable external ingress surfaces immediately in Console → Trust → Security without revoking SSO accounts or deleting integrations. Surface flags fail closed on error:
service— Freezes allPOST /servicemachine connector calls org-wide.mcp— Freezes/mcp*endpoints org-wide (or toggletools,analytics,memory,sandbox, anddelegateindividually).external_surfaces— Cuts live/e/:slughosted pages andnes_*embed sessions immediately.sidecar&channels— Freezes workstation Sidecar bridges or Slack/Teams/Webhook channels.
| Status Code | Meaning |
|---|---|
| 401 Unauthorized | Missing, expired, or revoked token (sets X-Token-Expired: true on expired SSO JWTs; emits WWW-Authenticate OAuth challenge on /mcp*). |
| 403 Forbidden | Key type not permitted on this surface (for example a service key calling /api/* or any nunc_* key calling an admin endpoint), surface kill switch active, or PBAC/Guardian policy block. |
| 409 Conflict | Mutating tool paused at a human write-approval gate; resume after approval in Console, Studio, or Slack. |
| 429 Too Many Requests | Per-user, per-application, or tenant rate limit / token budget reached. |