Service Connections API (/service)
POST /service is Nunc's dedicated machine-to-machine data plane for backend microservices, scheduled sync jobs, and internal portals. It speaks the same JSON-RPC 2.0 tools/list and tools/call wire protocol as /mcp, but admits only non-human Service Application principals (type="service") and cannot access Nunc's internal /api/* or /chat/completions routes.
https://api.nunc.cloud/servicehttps://api.nunc.cloud/service/health1. How /service is isolated from Nunc UI APIs and /mcp
Nunc enforces strict lane separation at the gateway authentication layer. The endpoint a credential enters determines both what it is permitted to reach and which runtime pipeline executes:
| Dimension | Service Lane (POST /service) | AI Assistant Lane (POST /mcp*) | Nunc Control & Engine (/api/*, /chat/*) |
|---|---|---|---|
| Admitted Principals | Application keys (app_*) with type="service" only. Rejects humans, OAuth tokens, and chat apps with 403. | Human OAuth 2.1 PKCE sessions (plus federated app keys on /mcp). | First-party Nunc SSO JWTs (and chat app keys on non-admin engine routes). Service keys are blocked (403). |
| Runtime Pipeline | Authenticate → Application tool-grant check → rate-limit & budget → egress allowlist → SHA-256 audit record. Full deterministic payloads returned inline. | 6-stage Guardian prompt-injection & secret scanner, outbound [REDACTED:TYPE] PII masking, User/Group/Org PBAC, and human write gates. | Strict first-party CORS + CORP, reversible ⟦PII:TYPE#N⟧ tokenization, workspace memory, and admin RBAC. |
| Tool Scope | Explicit per-application allowlist, including machine-only *_svc_* sync tools that human MCP users cannot invoke. | Human-permitted SaaS, SQL, memory, sandbox, and specialist delegation tools. | Tenant administration, chat completions, workflows, datasets, and Data Studio artifacts. |
| Browser Access | Server-to-server only (no browser OAuth challenge, CORP: same-origin). | OAuth 2.1 PKCE discovery (/.well-known) for approved AI clients. | Locked to Nunc Console/Studio origins (plus CSP frame-ancestors for /e/:slug). |
2. Configure a Service Connection in Nunc Console
Registering non-human Application principals requires Tenant Admin permissions on an Enterprise plan (or the applications plan add-on; Core plans without the add-on return 403 applications_enterprise_required).
- Connect the upstream integration with an organization credential: Open Console → Build → Integrations and authenticate the target system (for example Salesforce, Sage Intacct, NetSuite, Cvent, or Postgres) using an organization-level service account rather than a personal per-user login.
- Register a Service Application: Open Console → Build → Applications and click New Application. Enter a lowercase slug handle (for example
billing-sync) and set Application Type toservice. Nunc creates a non-human principal (app_<hex>) that never appears in the human People roster and audits under its own application handle. - Assign explicit tool grants (default-deny): In the Application's Tool Grants tab, select the exact connector tools this service may invoke (for example
salesforce_query_accountsandintacct_list_invoices). Any tool omitted from the Application grant list returns403even if enabled for human users. - Mint and store the Application key: Open the API Keys tab on that Application and click Mint Key. Copy the
nunc_<hex>secret into your backend secret manager immediately. Nunc stores only the SHA-256 hash and displays the raw value once. - Verify the tenant Service kill switch: Confirm the Service API surface toggle is enabled in Console → Trust → Security. Test connectivity with
GET https://api.nunc.cloud/service/health, which returns{"ok":true,"lane":"service"}.
3. Call POST /service (JSON-RPC 2.0)
Send POST requests to https://api.nunc.cloud/service with Authorization: Bearer <nunc_service_key>. When sending optional routing headers (Mcp-Method or Mcp-Name), ensure they exactly match the JSON-RPC body method and params.name; the gateway rejects mismatched headers with -32020 to prevent proxy request smuggling.
List granted tools (tools/list)
curl -sS -X POST https://api.nunc.cloud/service \
-H "Authorization: Bearer $NUNC_SERVICE_KEY" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
}'Execute a connector tool (tools/call)
curl -sS -X POST https://api.nunc.cloud/service \
-H "Authorization: Bearer $NUNC_SERVICE_KEY" \
-H "Content-Type: application/json" \
-H "Mcp-Method: tools/call" \
-H "Mcp-Name: salesforce_query_accounts" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "salesforce_query_accounts",
"arguments": {
"segment": "enterprise",
"limit": 50
}
}
}'TypeScript / Node.js backend helper
const SERVICE_URL = "https://api.nunc.cloud/service";
interface JsonRpcResponse<T> {
jsonrpc: "2.0";
id: number | string | null;
result?: T;
error?: { code: number; message: string; data?: unknown };
}
export async function callNuncServiceTool<T = unknown>(
toolName: string,
args: Record<string, unknown>,
): Promise<T> {
const response = await fetch(SERVICE_URL, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.NUNC_SERVICE_KEY}`,
"Content-Type": "application/json",
"Mcp-Method": "tools/call",
"Mcp-Name": toolName,
},
body: JSON.stringify({
jsonrpc: "2.0",
id: crypto.randomUUID(),
method: "tools/call",
params: { name: toolName, arguments: args },
}),
});
const payload = (await response.json()) as JsonRpcResponse<T>;
if (!response.ok || payload.error) {
throw new Error(
`Nunc /service ${response.status}: ${payload.error?.message ?? response.statusText}`,
);
}
return payload.result as T;
}4. Supported JSON-RPC methods & error codes
| JSON-RPC Method | Purpose |
|---|---|
| server/discover · initialize | Negotiate protocol version (2026-07-28 through 2024-11-05) and inspect server capabilities. |
| tools/list | Return JSON Schemas for the exact tools granted to the calling app_* Service Application. |
| tools/call | Execute a granted tool synchronously (or return a durable task handle when the caller declares task capability). |
| tasks/get · tasks/result · tasks/cancel | Poll, retrieve output, or cancel long-running asynchronous tool executions. |
| HTTP / JSON-RPC Code | Cause & Resolution |
|---|---|
| 401 / -32001 | Missing, invalid, or revoked Bearer nunc_* key, or suspended tenant. Rotate the key in Console → Build → Applications. |
| 403 / -32003 | Caller authenticated with a human key, OAuth token, or chat/federated app key; the requested tool is not granted to this Application; or the tenant service surface switch is disabled. |
| 400 / -32020 | Malformed JSON-RPC payload (-32700) or Mcp-Method / Mcp-Name header mismatch (-32020). |
| 429 / -32005 | Tenant mcp_tool_call rate limit reached. Inspect error.data.resetAt before retrying. |
| 508 / -32003 | Loop protection triggered because a downstream connector attempted to call back into Nunc recursively. |