Express.js AI agent API key management: scoped vault keys for Node agent backends

The Express AI agent tool backend pattern

A typical Express AI agent tool backend looks like this:

import express from "express";
import Stripe from "stripe";

const app = express();
app.use(express.json());

const stripe = new Stripe(process.env.STRIPE_KEY);  // shared across ALL requests

app.post("/tools/charge", async (req, res) => {
  const { amount, customerId } = req.body;
  const intent = await stripe.paymentIntents.create({
    amount,
    currency: "usd",
    customer: customerId,
  });
  res.json(intent);
});

This is clean Node.js. The problem: the Stripe instance is initialized once at module load with the same API key for every concurrent request. A stuck agent loop creating payment intents for User A can also hit endpoints that should be locked to User B's data — there's no request-scoped enforcement boundary. Rotating the key to kill the runaway agent disrupts every active session simultaneously.

Adding vault keys via Express middleware

Express middleware runs before route handlers and has access to the req and res objects that routes already use:

import fetch from "node-fetch"; // or native fetch in Node 18+

async function vaultKeyMiddleware(req, res, next) {
  // Skip non-agent routes (health checks, static assets, etc.)
  if (!req.path.startsWith("/tools/")) {
    return next();
  }

  const userId = req.headers["x-user-id"] ?? "anonymous";
  const runId = req.headers["x-agent-run-id"] ?? "unknown";

  try {
    const issueResp = 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: `express-${userId}-${runId}`,
        vendor: "stripe",
        allowed_endpoints: [
          "/v1/payment_intents",
          "/v1/payment_intents/*",
        ],
        daily_usd_cap: 500,
        expires_in: "5m",
      }),
    });

    if (!issueResp.ok) throw new Error(`Keybrake issuance: ${issueResp.status}`);
    const keyData = await issueResp.json();
    req.vaultKey = keyData.token;
    req.vaultKeyId = keyData.id;
  } catch (err) {
    console.error("Vault key issuance failed:", err);
    req.vaultKey = null;
    req.vaultKeyId = null;
  }

  // Revoke vault key after the response body is finished
  res.on("finish", async () => {
    if (req.vaultKeyId) {
      try {
        await fetch(`https://api.keybrake.com/v1/keys/${req.vaultKeyId}`, {
          method: "DELETE",
          headers: { "Authorization": `Bearer ${process.env.KEYBRAKE_TOKEN}` },
        });
      } catch (_) {
        // Key expires via TTL if revocation fails — acceptable
      }
    }
  });

  next();
}

app.use(vaultKeyMiddleware);

Route handlers now use the per-request vault key from req.vaultKey:

app.post("/tools/charge", async (req, res) => {
  if (!req.vaultKey) {
    return res.status(503).json({ error: "vault_key_unavailable" });
  }

  const resp = await fetch(
    "https://proxy.keybrake.com/stripe/v1/payment_intents",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${req.vaultKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        amount: req.body.amount,
        currency: "usd",
        customer: req.body.customerId,
      }),
    }
  );

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

  if (!resp.ok) {
    return res.status(resp.status).json(await resp.json());
  }

  res.json(await resp.json());
});

Using vault keys with the Stripe Node SDK's custom base URL

If you prefer the Stripe SDK's typed methods over raw fetch calls, the Stripe Node SDK v8+ supports custom base URLs via StripeClient. This lets you keep your existing Stripe SDK usage while routing through the Keybrake proxy:

import Stripe from "stripe";

// In your route handler or a per-request factory:
function createStripeClient(vaultKey) {
  return new Stripe(vaultKey, {
    // Route through Keybrake proxy instead of api.stripe.com
    host: "proxy.keybrake.com",
    protocol: "https",
    path: "/stripe",
  });
}

app.post("/tools/charge", async (req, res) => {
  const stripeClient = createStripeClient(req.vaultKey);
  const intent = await stripeClient.paymentIntents.create({
    amount: req.body.amount,
    currency: "usd",
    customer: req.body.customerId,
  });
  res.json(intent);
});

This is the cleanest migration path if you have existing Stripe SDK calls — minimal code changes, same typed API, policy enforcement handled by the proxy.

Express with Bull/BullMQ: vault keys for async agent queues

Many Express AI agent backends use Bull or BullMQ for async task processing. The vault key from the Express middleware does not cross the queue boundary. Issue a fresh vault key inside the Bull worker's process callback:

import { Worker } from "bullmq";
import fetch from "node-fetch";

const billingWorker = new Worker("billing-agent", async (job) => {
  const { runId, customerIds } = job.data;

  // Issue vault key at worker process start — not in Express middleware
  const issueResp = 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: `bull-billing-${runId}`,
      vendor: "stripe",
      allowed_endpoints: ["/v1/payment_intents", "/v1/payment_intents/*"],
      daily_usd_cap: 5000,
      expires_in: "30m",
    }),
  });

  const { token: vaultKey, id: vaultKeyId } = await issueResp.json();

  try {
    for (const customerId of customerIds) {
      await chargeCustomer(customerId, vaultKey);
    }
  } finally {
    await fetch(`https://api.keybrake.com/v1/keys/${vaultKeyId}`, {
      method: "DELETE",
      headers: { "Authorization": `Bearer ${process.env.KEYBRAKE_TOKEN}` },
    });
  }
});

Concurrency and performance considerations

Get early access

Related questions

Further reading

• NestJS AI agent API key — vault key integration for NestJS using dependency injection and NestJS interceptors, which provide a cleaner separation of concerns than Express middleware for TypeScript projects.
• Vercel AI SDK + Stripe — vault key patterns for Next.js API routes and Vercel AI SDK tool calls, which wrap Express or Node.js http under the hood.
• AI agent API key lifecycle — the four lifecycle phases (issuance, enforcement, expiration, revocation) and how they map to Express's middleware and response lifecycle.
• AI agent error handling — how to handle 429 spend-cap responses, retry logic, and error propagation in Node.js AI agent backends calling vendor APIs through a proxy.
• Django AI agent API key — the same vault key pattern for Django backends using Python middleware, for teams with a Python agent backend alongside their Node.js services.