Docs/Service Connections (/service)
Public Machine APIPOST https://api.nunc.cloud/service · JSON-RPC 2.0 · Enterprise

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/service
https://api.nunc.cloud/service/health

1. 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:

DimensionService Lane (POST /service)AI Assistant Lane (POST /mcp*)Nunc Control & Engine (/api/*, /chat/*)
Admitted PrincipalsApplication 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 PipelineAuthenticate → 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 ScopeExplicit 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 AccessServer-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).

  1. 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.
  2. 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 to service. Nunc creates a non-human principal (app_<hex>) that never appears in the human People roster and audits under its own application handle.
  3. 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_accounts and intacct_list_invoices). Any tool omitted from the Application grant list returns 403 even if enabled for human users.
  4. 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.
  5. 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 MethodPurpose
server/discover · initializeNegotiate protocol version (2026-07-28 through 2024-11-05) and inspect server capabilities.
tools/listReturn JSON Schemas for the exact tools granted to the calling app_* Service Application.
tools/callExecute a granted tool synchronously (or return a durable task handle when the caller declares task capability).
tasks/get · tasks/result · tasks/cancelPoll, retrieve output, or cancel long-running asynchronous tool executions.
HTTP / JSON-RPC CodeCause & Resolution
401 / -32001Missing, invalid, or revoked Bearer nunc_* key, or suspended tenant. Rotate the key in Console → Build → Applications.
403 / -32003Caller 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 / -32020Malformed JSON-RPC payload (-32700) or Mcp-Method / Mcp-Name header mismatch (-32020).
429 / -32005Tenant mcp_tool_call rate limit reached. Inspect error.data.resetAt before retrying.
508 / -32003Loop protection triggered because a downstream connector attempted to call back into Nunc recursively.