AWS Lambda AI agent API key: scoping vendor calls in event-driven agent functions

How Lambda AI agent functions call vendor APIs

A typical event-driven agent Lambda reads STRIPE_SECRET_KEY from environment variables and calls Stripe for each SQS message:

// Typical pattern — problematic for agent workloads
exports.handler = async (event) => {
  const stripeKey = process.env.STRIPE_SECRET_KEY;  // same key for ALL invocations

  for (const record of event.Records) {
    const body = JSON.parse(record.body);

    const res = await fetch('https://api.stripe.com/v1/payment_intents', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${stripeKey}`,
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        amount: body.amount_cents,
        currency: 'usd',
        customer: body.customer_id
      })
    });

    if (!res.ok) throw new Error(`Stripe error: ${res.status}`);
  }
};

This pattern has three compounding risks specific to Lambda. First, if the SQS queue contains 1,000 messages, Lambda's automatic concurrency scaling can dispatch up to 1,000 concurrent function invocations simultaneously — all using the same STRIPE_SECRET_KEY, with no dollar cap across the invocations. Reserved concurrency limits the count, not the spend. Second, when a Lambda invocation fails (throws an unhandled exception), SQS redelivers the message up to the queue's maxReceiveCount — typically 3–5 times. If the function threw after Stripe had applied a charge, the redelivery retries the Stripe call without an idempotency key, creating duplicate charges. Third, EventBridge event buses retry failed Lambda targets for up to 24 hours by default — the same vendor API call is re-attempted across multiple invocations without charge deduplication.

Three gaps Lambda's native tooling doesn't fill for vendor spend control

The concurrency burst amplification risk

Lambda's automatic scaling is designed to process queue backlogs as fast as possible. When a SQS queue accumulates a backlog, Lambda scales aggressively — adding up to 1,000 concurrent executions per minute until the queue is cleared (within the reserved concurrency limit). For agent billing functions, this means a queue that backed up overnight due to an upstream delay can trigger 500 concurrent Lambda invocations simultaneously when it is unblocked — 500 concurrent Stripe calls with no dollar cap. The speed that makes Lambda efficient for processing becomes a liability when each execution has an unbounded cost.

SQS's dead-letter queue behavior adds a deduplication gap. By default, SQS Standard queues have at-least-once delivery — the same message can be delivered multiple times, and the Lambda function may be invoked twice for the same message if the first invocation didn't delete it in time. Without a stable idempotency key (the SQS messageId is stable across redeliveries), two Lambda invocations processing the same message make two independent Stripe calls.

Scoping vault keys per Lambda event

const { SSMClient, GetParameterCommand } = require('@aws-sdk/client-ssm');

const ssm = new SSMClient({ region: process.env.AWS_REGION });
const KEYBRAKE_BASE = 'https://proxy.keybrake.com';

// Process-level cache — survives warm starts, not cold starts
let keybrakeApiKey;

async function getKeybrakeApiKey() {
  if (!keybrakeApiKey) {
    const { Parameter } = await ssm.send(new GetParameterCommand({
      Name: '/keybrake/api-key',
      WithDecryption: true
    }));
    keybrakeApiKey = Parameter.Value;
  }
  return keybrakeApiKey;
}

async function issueVaultKey(apiKey, messageId, budgetUsd) {
  const res = await fetch(`${KEYBRAKE_BASE}/vault/keys`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      vendor: 'stripe',
      daily_usd_cap: budgetUsd,
      allowed_endpoints: ['POST /v1/payment_intents'],
      expires_in: '15m',  // matches Lambda max timeout
      agent_run_label: `lambda/${process.env.AWS_LAMBDA_FUNCTION_NAME}/${messageId}`
    })
  });
  if (!res.ok) throw new Error(`Keybrake error: ${res.status}`);
  return res.json();
}

exports.handler = async (event) => {
  const apiKey = await getKeybrakeApiKey();
  const failedItems = [];

  for (const record of event.Records) {
    const body = JSON.parse(record.body);
    const messageId = record.messageId;  // stable across SQS redeliveries

    try {
      // Issue a vault key scoped to this message / agent run
      const vault = await issueVaultKey(apiKey, messageId, body.budget_usd ?? 100);

      const res = await fetch(`${KEYBRAKE_BASE}/stripe/v1/payment_intents`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${vault.vault_key}`,
          'Idempotency-Key': messageId,  // SQS dedup + Stripe dedup — same value
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          amount: body.amount_cents,
          currency: 'usd',
          customer: body.customer_id
        })
      });

      if (res.status === 429) {
        const err = await res.json();
        if (err.code === 'cap_exhausted') {
          // Cap hit: move to DLQ without retrying — it's intentional, not transient
          failedItems.push({ itemIdentifier: record.messageId });
          continue;
        }
      }

      if (!res.ok) throw new Error(`Stripe error: ${res.status}`);
    } catch (err) {
      if (err.message.startsWith('CapExhausted')) {
        failedItems.push({ itemIdentifier: record.messageId });
      } else {
        throw err;  // re-throw transient errors for SQS retry
      }
    }
  }

  // Partial batch response: only failed items are retried by SQS
  return { batchItemFailures: failedItems };
};

The KEYBRAKE_API_KEY is fetched from SSM Parameter Store once per cold start and cached at process level — warm invocations reuse the cached value without an SSM call. A separate vault key is issued per SQS message (per agent run), with a 15-minute TTL matching the Lambda maximum timeout. The vault key's agent_run_label includes the function name and messageId, making every vendor call in the audit log traceable to the specific SQS message that triggered it. Using messageId as both the vault key label and the Stripe Idempotency-Key makes SQS redeliveries and Stripe retries idempotent with the same key. Partial batch response (batchItemFailures) ensures cap-exhausted messages are sent to the DLQ rather than blocking the entire batch retry.

How Keybrake fits

Keybrake is the proxy layer between your agent Lambda functions and Stripe, Twilio, or Resend. The vault key issued per SQS message replaces the STRIPE_SECRET_KEY previously stored in Lambda environment variables or fetched from Secrets Manager. The real Stripe secret stays in Keybrake — it is never present in Lambda environment variables, CloudWatch Logs, or SSM exports. Revoking a runaway Lambda invocation mid-execution is a single DELETE /vault/keys/{key_id} call — effective on the next proxied request, with no function redeploy, no Secrets Manager rotation, and no reserved concurrency change that would affect other functions sharing the same concurrency pool.

Get early access

Related questions

Further reading

• AWS Step Functions AI agent API key — for Lambda functions orchestrated by Step Functions Map states, where the vault key is issued in a preceding Task state rather than within the Lambda handler.
• AI agent idempotency — why SQS messageId as the idempotency key is safe and why random UUIDs at invocation time create duplicate charges on redelivery.
• AI agent spend reporting — the four reporting queries that give per-run cost visibility using the vault_key audit log that Lambda's built-in tooling doesn't provide.
• AI agent API key best practices — the seven operational controls for event-driven agent functions, including how to handle Lambda's process-level env var caching.