Next.js AI agent API key management: vault keys via Route Handlers and middleware

The standard Next.js AI agent tool pattern and its problem

A typical Next.js AI agent tool Route Handler for a Stripe charge looks like this:

// app/api/tools/charge/route.ts
import { NextRequest, NextResponse } from "next/server";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: NextRequest) {
  const { amount, customerId } = await req.json();

  const intent = await stripe.paymentIntents.create({
    amount,
    currency: "usd",
    customer: customerId,
  });

  return NextResponse.json({ clientSecret: intent.client_secret });
}

The stripe instance is initialized at module load time — once per Next.js server process — and shared across all requests. In development, hot-reload recreates it on each change. In production on Vercel, each serverless function invocation may create a fresh instance but all share the same STRIPE_SECRET_KEY env var. Multiple concurrent agent sessions — from different users, different agent runs, or the same user's parallel tool calls — all share the same credential with no isolation between them.

Adding vault keys to a Next.js Route Handler

Replace the direct Stripe SDK call with a Keybrake vault key issued per-request:

// app/api/tools/charge/route.ts
import { NextRequest, NextResponse } from "next/server";

async function issueVaultKey(label: string) {
  const resp = await fetch("https://api.keybrake.com/v1/keys", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KEYBRAKE_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      label,
      vendor: "stripe",
      allowed_endpoints: ["/v1/payment_intents", "/v1/payment_intents/*"],
      daily_usd_cap: 500,
      expires_in: "5m",
    }),
  });
  if (!resp.ok) throw new Error(`Vault key issuance failed: ${resp.status}`);
  return resp.json() as Promise<{ id: string; token: string }>;
}

async function revokeVaultKey(id: string) {
  await fetch(`https://api.keybrake.com/v1/keys/${id}`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${process.env.KEYBRAKE_TOKEN}` },
  }).catch(() => {}); // TTL is the safety net
}

export async function POST(req: NextRequest) {
  const { amount, customerId } = await req.json();
  const userId = req.headers.get("x-user-id") ?? "anon";
  const runId = req.headers.get("x-agent-run-id") ?? "unknown";

  const vaultKey = await issueVaultKey(`nextjs-${userId}-${runId}`);

  try {
    const resp = await fetch(
      "https://proxy.keybrake.com/stripe/v1/payment_intents",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${vaultKey.token}`,
          "Content-Type": "application/x-www-form-urlencoded",
        },
        body: new URLSearchParams({
          amount: String(amount),
          currency: "usd",
          customer: customerId,
        }),
      },
    );

    if (resp.status === 429) {
      const body = await resp.json();
      if (body.code === "cap_exhausted") {
        return NextResponse.json(
          { error: "spend_cap_exceeded" },
          { status: 402 },
        );
      }
    }

    if (!resp.ok) {
      return NextResponse.json({ error: "stripe_error" }, { status: 502 });
    }

    const intent = await resp.json();
    return NextResponse.json({ clientSecret: intent.client_secret });
  } finally {
    await revokeVaultKey(vaultKey.id);
  }
}

The vault key is issued at the top of the handler, used for one Stripe call, and revoked in the finally block. If the handler throws or times out, the TTL ensures revocation. The Stripe SDK is no longer needed — the proxy accepts standard Stripe API requests over HTTP.

Vault keys with Vercel AI SDK streaming

The Vercel AI SDK's streamText function is common for streaming agent responses in Next.js. Vault keys work, but the lifecycle wraps the stream setup, not consumption:

// app/api/agent/route.ts
import { NextRequest } from "next/server";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";

export async function POST(req: NextRequest) {
  const { messages } = await req.json();
  const userId = req.headers.get("x-user-id") ?? "anon";

  // Issue vault key before the agent stream starts
  const vaultKey = await issueVaultKey(`ai-sdk-stream-${userId}`);

  // Pass vault key to tool implementations via closure
  const result = streamText({
    model: openai("gpt-4o"),
    messages,
    tools: {
      chargeCustomer: {
        description: "Charge a customer via Stripe",
        parameters: z.object({
          amount: z.number(),
          customerId: z.string(),
        }),
        execute: async ({ amount, customerId }) => {
          // Uses the vault key from the outer closure
          const resp = await fetch(
            "https://proxy.keybrake.com/stripe/v1/payment_intents",
            {
              method: "POST",
              headers: { Authorization: `Bearer ${vaultKey.token}` },
              body: new URLSearchParams({
                amount: String(amount),
                currency: "usd",
                customer: customerId,
              }),
            },
          );
          return resp.json();
        },
      },
    },
    onFinish: async () => {
      // Revoke when the stream completes
      await revokeVaultKey(vaultKey.id);
    },
  });

  return result.toDataStreamResponse();
}

For streaming, the vault key TTL must cover the maximum expected stream duration — a 5-minute TTL covers most agent runs, but long-running multi-step agents may need 15–30 minutes. Set the TTL to the maximum expected agent session length, not to the average.

Next.js deployment contexts and vault key behavior

Shared helper for all Route Handlers

Extract vault key management into a shared utility to avoid repeating it in every Route Handler:

// lib/vault.ts
export interface VaultKey {
  id: string;
  token: string;
}

export async function withVaultKey<T>(
  label: string,
  vendor: string,
  options: {
    allowed_endpoints?: string[];
    daily_usd_cap?: number;
    expires_in?: string;
  },
  fn: (token: string) => Promise<T>,
): Promise<T> {
  const resp = await fetch("https://api.keybrake.com/v1/keys", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KEYBRAKE_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ label, vendor, ...options }),
  });

  if (!resp.ok) throw new Error(`Vault key issuance failed: ${resp.status}`);
  const key: VaultKey = await resp.json();

  try {
    return await fn(key.token);
  } finally {
    fetch(`https://api.keybrake.com/v1/keys/${key.id}`, {
      method: "DELETE",
      headers: { Authorization: `Bearer ${process.env.KEYBRAKE_TOKEN}` },
    }).catch(() => {});
  }
}

// Usage in a Route Handler:
export async function POST(req: NextRequest) {
  const { amount, customerId } = await req.json();

  return withVaultKey(
    "charge-tool",
    "stripe",
    { allowed_endpoints: ["/v1/payment_intents"], daily_usd_cap: 500 },
    async (token) => {
      const resp = await fetch(
        "https://proxy.keybrake.com/stripe/v1/payment_intents",
        { method: "POST", headers: { Authorization: `Bearer ${token}` }, ... },
      );
      return NextResponse.json(await resp.json());
    },
  );
}

Get early access

Related questions

Further reading

• Vercel AI SDK + Stripe — vault key patterns specifically for the Vercel AI SDK's streamText and generateText tool execution model.
• NestJS AI agent API key — the same vault key pattern for NestJS backends, using interceptors and REQUEST-scoped dependency injection instead of Route Handlers.
• Express.js AI agent API key — plain Express middleware pattern for teams not using the Next.js framework layer.
• AI agent API key lifecycle — the four lifecycle phases (issuance, enforcement, expiration, revocation) and how they map to Next.js's request/response model.
• AI agent sandbox execution — credential safety for sandboxed code execution environments (E2B, Modal) that are sometimes spawned from Next.js Route Handlers.