Docs/API Gating & REST Reference
Gateway Boundaries & Engine APIhttps://api.nunc.cloud · Zero /v1 Prefix · Strict Principal Gating

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.cloud

Looking 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:

  1. 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) with Cross-Origin-Resource-Policy: same-origin. External web origins cannot call /api/* from a browser.
  2. 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 every nunc_* API key with 403 Tenant admin role required. Only a human Console SSO JWT carrying the admin or owner role is accepted.
  3. Application type gating (service vs. chat vs. federated): Non-human nunc_* keys are bound to an app_<hex> principal whose type strictly restricts which surfaces accept it:
    • type="service" — Admitted on POST /service (and headless /mcp connector calls). Hard-blocked (403) on all /api/* routes, /chat/completions, /mcp/memory, /mcp/analytics, and /mcp/sandbox.
    • type="chat" — Admitted on POST /chat/completions and non-admin /api/* engine routes for @nunc/sdk. Hard-blocked (403) on /service and /mcp*.
    • type="federated" — Admitted on /mcp (Guardian-scanned MCP tool federation) and non-admin /api/* routes. Hard-blocked (403) on /chat/completions and /service.
  4. Human-only MCP surfaces & OAuth 2.1 audience binding: /mcp/analytics, /mcp/memory, and /mcp/sandbox reject all Application principals (403) and require an interactive human OAuth 2.1 PKCE token bound to that exact resource URL (RFC 8707).
  5. Ephemeral Web Embed sessions (nes_*): Published widgets (/embed.js, /e/:slug) exchange a host-signed identity JWT at POST /e/:slug/session for a 24-hour Bearer nes_<hex> token (ext:<appId>:<sub>) accepted only on POST /chat/completions and locked to configured allowed_origins via CSP frame-ancestors.

2. Principal & surface access matrix

Credential / PrincipalConsole 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)AllowedAllowedAllowedVia OAuth 2.1Denied (403)
Nunc Member / Viewer (SSO JWT)Denied (403)Allowed (viewer read-only)AllowedVia OAuth 2.1Denied (403)
Human OAuth 2.1 PKCE TokenDenied (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).

DomainRoutesAccepted Credentials
Service Data PlanePOST /service
GET /service/health
Bearer nunc_* bound to type="service" Application only. See /docs/service-api.
Chat & ApprovalsPOST /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 EmbedGET /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 & RunsPOST /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 SandboxPOST /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 & KnowledgePOST /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 AdminGET/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 all POST /service machine connector calls org-wide.
  • mcp — Freezes /mcp* endpoints org-wide (or toggle tools, analytics, memory, sandbox, and delegate individually).
  • external_surfaces — Cuts live /e/:slug hosted pages and nes_* embed sessions immediately.
  • sidecar & channels — Freezes workstation Sidecar bridges or Slack/Teams/Webhook channels.
Status CodeMeaning
401 UnauthorizedMissing, expired, or revoked token (sets X-Token-Expired: true on expired SSO JWTs; emits WWW-Authenticate OAuth challenge on /mcp*).
403 ForbiddenKey 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 ConflictMutating tool paused at a human write-approval gate; resume after approval in Console, Studio, or Slack.
429 Too Many RequestsPer-user, per-application, or tenant rate limit / token budget reached.