NestJS AI agent API key management: vault keys via interceptors and dependency injection

The NestJS AI agent tool backend pattern

A typical NestJS AI agent tool backend looks like this:

import { Controller, Post, Body, Injectable } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import Stripe from "stripe";

@Injectable()
export class StripeService {
  private stripe: Stripe;

  constructor(private config: ConfigService) {
    // Initialized once per application lifecycle — shared across ALL requests
    this.stripe = new Stripe(config.get("STRIPE_KEY"));
  }

  async createIntent(amount: number, customerId: string) {
    return this.stripe.paymentIntents.create({
      amount,
      currency: "usd",
      customer: customerId,
    });
  }
}

@Controller("tools")
export class AgentToolController {
  constructor(private stripeService: StripeService) {}

  @Post("charge")
  async charge(@Body() body: ChargeDto) {
    return this.stripeService.createIntent(body.amount, body.customerId);
  }
}

This is idiomatic NestJS with dependency injection. The problem: StripeService is a singleton by default — one instance per application, initialized once, shared across all requests. Every concurrent agent call uses the same stripe instance with the same API key. Spend by one user's agent is indistinguishable from spend by another's at the Stripe level.

Adding vault keys via NestJS interceptors

NestJS interceptors wrap the entire request lifecycle and have access to ExecutionContext and the response observable — the right place to issue vault keys before the controller and revoke them after:

import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
} from "@nestjs/common";
import { Observable } from "rxjs";
import { finalize } from "rxjs/operators";
import fetch from "node-fetch";

@Injectable()
export class VaultKeyInterceptor implements NestInterceptor {
  async intercept(
    context: ExecutionContext,
    next: CallHandler,
  ): Promise<Observable<any>> {
    const request = context.switchToHttp().getRequest();

    // Skip non-agent routes
    if (!request.path.startsWith("/tools/")) {
      return next.handle();
    }

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

    let vaultKeyId: string | null = null;

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

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

    return next.handle().pipe(
      finalize(async () => {
        if (vaultKeyId) {
          try {
            await fetch(`https://api.keybrake.com/v1/keys/${vaultKeyId}`, {
              method: "DELETE",
              headers: {
                Authorization: `Bearer ${process.env.KEYBRAKE_TOKEN}`,
              },
            });
          } catch (_) {
            // TTL is the safety net — revocation failure is non-critical
          }
        }
      }),
    );
  }
}

Register the interceptor globally in your app module, or per-controller using @UseInterceptors(VaultKeyInterceptor):

// Option 1: global (applies to all routes)
import { APP_INTERCEPTOR } from "@nestjs/core";

@Module({
  providers: [
    { provide: APP_INTERCEPTOR, useClass: VaultKeyInterceptor },
  ],
})
export class AppModule {}

// Option 2: per-controller
@Controller("tools")
@UseInterceptors(VaultKeyInterceptor)
export class AgentToolController { ... }

Accessing the vault key in services via REQUEST scope

NestJS's default singleton scope means services can't access the per-request vault key directly. Use REQUEST-scoped providers to inject the vault key into services that need it:

import { Injectable, Scope, Inject } from "@nestjs/common";
import { REQUEST } from "@nestjs/core";
import { Request } from "express";
import fetch from "node-fetch";

@Injectable({ scope: Scope.REQUEST })
export class ProxyStripeService {
  constructor(@Inject(REQUEST) private request: Request) {}

  async createIntent(amount: number, customerId: string) {
    const vaultKey = (this.request as any).vaultKey;
    if (!vaultKey) throw new Error("No vault key available for this request");

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

    if (resp.status === 429) {
      const body: any = await resp.json();
      if (body.code === "cap_exhausted") {
        throw new Error("SPEND_CAP_EXCEEDED");
      }
    }

    if (!resp.ok) throw new Error(`Stripe proxy: ${resp.status}`);
    return resp.json();
  }
}

// Controller with REQUEST-scoped service injection
@Controller("tools")
@UseInterceptors(VaultKeyInterceptor)
export class AgentToolController {
  constructor(private proxyStripeService: ProxyStripeService) {}

  @Post("charge")
  async charge(@Body() body: ChargeDto) {
    try {
      return await this.proxyStripeService.createIntent(
        body.amount,
        body.customerId,
      );
    } catch (err) {
      if (err.message === "SPEND_CAP_EXCEEDED") {
        throw new HttpException("spend_cap_exceeded", HttpStatus.PAYMENT_REQUIRED);
      }
      throw err;
    }
  }
}

REQUEST-scoped providers cascade: any singleton that injects a REQUEST-scoped provider automatically becomes REQUEST-scoped. Plan your provider scope graph before using REQUEST scope in deeply nested service trees — the NestJS docs cover the cascading rules in the injection context section.

Performance and DI scope considerations

Get early access

Related questions

Further reading

• Express.js AI agent API key — the same vault key pattern for plain Express middleware, for teams using Express without the NestJS framework layer.
• Vercel AI SDK + Stripe — vault key patterns for Next.js API routes and the Vercel AI SDK, which shares NestJS's TypeScript ecosystem but uses a different request model.
• AI agent API key lifecycle — the four lifecycle phases (issuance, enforcement, expiration, revocation) and how they map to NestJS's interceptor and observable model.
• AI agent error handling — handling 429 spend-cap responses, retry logic in NestJS exception filters, and error propagation patterns for agent tool backends.
• AI agent credential management — broader credential management architecture for TypeScript agent backends, including NestJS ConfigService, secrets management, and provider scope patterns.