Build approval flows with Nuvouch.

Build every request around four questions: who is this for, where did it come from, what is happening, and what will the user decide?

Keep the mental model simple. Use subject for the recipient, source for origin, action for the thing being approved, decisions for the buttons, and keep integrator-only data in metadata.

subject

Identifies the user who will receive the approval request.

subject: { id: "user_123" }

source

Identifies where the request originated.

source: {
  key: "stripe:acct_123",
  name: "Stripe",
}

• key is required and should be stable.
• name is optional and used for display.

action

Describes what is about to happen.

action: {
  type: "payment.authorization",
  title: "Approve payment",
  description: "Allow Billing Agent to charge $84.00",
}

• type is machine-readable.
• title is short.
• description explains the consequence.

amount

Used for financial requests and shown prominently in the UI.

amount: {
  value: 84.0,
  currency: "USD",
}

details

Additional user-visible information, kept as an ordered list.

details: [
  { label: "Merchant", value: "OpenAI API" },
  { label: "Billing period", value: "April 2026" },
]

• Safe to display.
• Keep entries ordered by importance.

actor

Who or what triggered the request.

actor: {
  type: "ai_agent",
  name: "Billing Agent",
}

risk

Explains why the request may need attention.

risk: {
  level: "medium",
  signals: ["automated_action", "usage_threshold_exceeded"],
}

• level is the summary.
• signals are the reasons.

decisions

The choices shown to the user.

decisions: [
  { label: "Approve", value: "approve" },
  { label: "Deny", value: "deny" },
]

metadata

Internal data for integrators. Returned in callbacks, not shown to users.

metadata: {
  orderId: "ord_123",
}

Integrating Nuvouch follows one simple pattern:

1. Link the user once if you need a durable subject record.
2. Create an approval request from your server.
3. Wait for the signed callback from Nuvouch.
4. Execute or block the action based on the user decision.

const approval = 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",
  },
});

// wait for signed callback
// capture or block based on decision

Nuvouch is an approval infrastructure that sits between an action and its execution. It allows integrators like payment platforms, APIs, and services to request user approval before completing sensitive operations. Nuvouch is not the payer, the merchant, or the payment processor in those flows.

Use Nuvouch when your system needs to answer:

• Should this payment really happen?
• Should this AI agent be allowed to act?
• Should this request be trusted?

Your system does not blindly execute actions. It asks the user first.

Use the same shape for payments, login checks, and AI agent actions. Only the labels and signals change.

Payment approval

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 for API usage",
  },
  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", "high_amount"],
  },
  decisions: [
    { label: "Approve", value: "approve" },
    { label: "Deny", value: "deny" },
  ],
  metadata: { orderId: "ord_123" },
});

Login from new device

await nuvouch.approvals.create({
  subject: { id: "user_123" },
  source: { key: "auth:primary", name: "Auth Service" },
  action: {
    type: "login.verification",
    title: "Approve login",
    description: "Confirm sign-in from a new device in Lagos",
  },
  details: [
    { label: "Device", value: "MacBook Pro" },
    { label: "Location", value: "Lagos, Nigeria" },
    { label: "Time", value: "April 27, 2026 09:14 UTC" },
  ],
  actor: { type: "system", name: "Authentication Service" },
  risk: {
    level: "high",
    signals: ["new_device", "location_mismatch"],
  },
  decisions: [
    { label: "Approve", value: "approve" },
    { label: "Deny", value: "deny" },
  ],
  metadata: { loginId: "login_123" },
});

AI agent action

await nuvouch.approvals.create({
  subject: { id: "user_123" },
  source: { key: "agent:billing-bot", name: "Billing Bot" },
  action: {
    type: "agent.tool_call",
    title: "Approve agent action",
    description: "Allow Billing Bot to update the invoice and send a refund",
  },
  details: [
    { label: "Tool", value: "refunds.create" },
    { label: "Invoice", value: "inv_789" },
    { label: "Amount", value: "$24.00" },
  ],
  actor: { type: "ai_agent", name: "Billing Bot" },
  risk: {
    level: "medium",
    signals: ["automated_action", "sensitive_resource"],
  },
  decisions: [
    { label: "Approve", value: "approve" },
    { label: "Deny", value: "deny" },
  ],
  metadata: { traceId: "trace_abc" },
});

AI Agent
  ↓
Stripe (Source)
  ↓
Nuvouch (approval request)
  ↓
User Device (approve / deny)
  ↓
Nuvouch (signed callback)
  ↓
Stripe captures or blocks payment

1. Action is initiated by an app, API, workflow, or AI agent.
2. Your backend requests approval by sending the request to Nuvouch.
3. Nuvouch notifies the user on their trusted device.
4. The user approves or rejects in real time.
5. Nuvouch returns the decision using a signed callback.
6. You execute or block the action based on the callback.

Agent → Stripe → Nuvouch → User → Nuvouch → Stripe

• Source shown at the top.
• Title shown as the heading.
• Description shown below the heading.
• Amount highlighted prominently.
• Details shown as an ordered list.
• Risk indicators shown near the decision area.
• Decisions shown as buttons.

Use short, consistent signals. Keep them stable so policy, analytics, and UI can rely on them.

• automated_action
• new_device
• location_mismatch
• high_amount
• sensitive_resource

Keep signals short. Keep them consistent.

Integrator

Your platform, such as a payment provider, API, or service.

• Create approval requests.
• Handle signed callbacks.
• Execute or block actions.

User

The end user with a Nuvouch account and trusted device.

• Receive approval requests.
• Approve or reject actions.

Write titles and descriptions that explain the consequence, not just the existence of a prompt.

title: "Confirm"
description: "Approve this"

title: "Approve payment"
description: "Allow Billing Agent to charge $84.00 for API usage"

Without Nuvouch, actions happen automatically, users lose control, and fraud or mistakes become harder to prevent.

With Nuvouch, every sensitive action can be verified before execution, users stay in control, and systems become safer and more reliable.

OTP and traditional 2FA confirm access, but they usually do not describe the exact action being approved. Nuvouch is contextual: the user sees what is about to happen, who initiated it, and can approve or reject it before execution.

Approval requests should be treated as time-bound. If the user does not respond, the request can expire and your system should handle that outcome just like an approval or denial.

• Show pending state while the request is active.
• Handle expiry as a terminal outcome.
• Decide whether to retry, cancel, or ask the user again later.

1. Create an approval request from your server.
2. Wait for the signed callback.
3. Verify the callback.
4. Execute your business logic only after the verified decision.

• Getting started covers provisioning, callback setup, first-run flow, and the retry contract around externalRequestId.
• HTTP API reference gives you the raw endpoints, request payloads, response shapes, and stable error codes.
• Node SDK reference covers the typed client, helper utilities, and server-side callback verification helpers.
• MCP + OAuth covers the official hosted MCP path for OAuth-capable agent clients.
• AI Agent Auth covers direct runtime pairing, scoped delegation, provider introspection, and CLI usage.
• Webhook reference documents signed delivery verification, deduplication, retry behavior, and lifecycle events.
• Integration guide walks through the end-to-end payment authorization flow from subject linking to verified execution.