Nuvouch
Home
§ Setup · Prerequisites

What you need before the first request

  • An active integrator record with a configured callback URL.
  • The integrator callback secret stored server-side, either as NUVOUCH_CALLBACK_SECRET or in your secret manager.
  • An integrator API key for server-to-server requests.
  • A callback handler that can verify signatures and deduplicate deliveries.
  • The Nuvouch mobile app installed from Google Play open testing or the iOS TestFlight beta.
Mobile app beta now open

Install Nuvouch on a trusted device to review approval requests during integration testing.

Get it on Google PlayJoin on TestFlight
§ Setup · Server config

Configure your server runtime

.env
server environment
NUVOUCH_API_KEY=itg_live_xxxxx
NUVOUCH_CALLBACK_SECRET=nuvouch_live_callback_secret
Bootstrap the client
node sdk
import { Nuvouch } from "@nuvouch/node";

const nuvouch = new Nuvouch({
  apiKey: process.env.NUVOUCH_API_KEY,
});
// reads NUVOUCH_API_KEY

Public docs use x-api-key as the canonical request header. The backend also accepts Authorization: Bearer <key>, but standardizing on one header keeps support and logging simpler.

In the integrator console, treat NUVOUCH_CALLBACK_SECRET as the canonical server env var name for the callback secret you receive or rotate there. If your platform uses a secret manager instead of env vars, store the same value there and resolve it when verifying callbacks.

secret-manager.ts
no env required
import { Nuvouch } from "@nuvouch/node";

const nuvouch = new Nuvouch({ apiKey: process.env.NUVOUCH_API_KEY });

const callbackSecret = await secrets.get("integrations/nuvouch/callback-secret");

const event = nuvouch.webhooks.verify({
  secret: callbackSecret,
  rawBody,
  signature: req.headers.get("x-nuvouch-signature"),
});
§ Setup · First loop

Run the first working loop

  1. Provision the callback URL and store the callback secret from the integrator console in your server config or secret manager.
  2. Create a connection session for your business subject and show the QR code or short code in your product.
  3. Wait for the signed nuvouch.connection.accepted callback before creating approvals for that subject.
  4. Create approval requests with a stable externalRequestId.
  5. Execute the business side effect only after a verified approval callback arrives.

Continue into the integration guide for the end-to-end payment authorization walkthrough.

§ Setup · Reliability

Idempotency and retries

Retry-safe approval creation
node sdk
import {
  NuvouchApiError,
} from "@nuvouch/node";

const externalRequestId = "payment_auth_001";

try {
  await nuvouch.approvals.create({
    subject: {
      id: "user_123",
    },
    source: {
      key: "stripe:acct_123",
      name: "Stripe",
    },
    action: {
      type: "payment.authorization",
      title: "Approve payment",
      description: "Allow Billing Agent to charge $84.00",
    },
    amount: {
      value: 84.0,
      currency: "USD",
    },
    details: [
      { label: "Merchant", value: "OpenAI API" },
      { label: "Billing period", value: "April 2026" },
    ],
    actor: {
      type: "ai_agent",
      name: "Billing Agent",
    },
    risk: {
      level: "medium",
      signals: ["automated_action", "usage_threshold_exceeded"],
    },
    decisions: [
      { label: "Approve", value: "approve" },
      { label: "Deny", value: "deny" },
    ],
    metadata: {
      orderId: "ord_123",
    },
    externalRequestId,
  });
} catch (error) {
  if (
    error instanceof NuvouchApiError &&
    error.code === "DUPLICATE_EXTERNAL_ID"
  ) {
    await nuvouch.approvals.retrieveByExternalId(externalRequestId);
  }
}
§ Setup · Environments

Staging and production safety

  • Keep callback secrets and API keys separate per environment.
  • Never point staging Nuvouch deployments at production callback URLs.
  • Verify signed callbacks and delivery retries in staging before production rollout.
  • Store callback secrets and API keys only in server-side config, never in browser bundles.
§ Next

Continue with the references

Move into the Node SDK reference, HTTP API reference, webhook reference, and MCP + OAuth, AI Agent Auth, plus the integration guide.