Restate AI agent API key: scoping vendor calls in durable service invocations

How Restate AI agent services call vendor APIs

A typical Restate billing service uses ctx.run() to wrap Stripe calls as exactly-once side effects:

import * as restate from "@restatedev/restate-sdk";
import Stripe from "stripe";

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

const billingService = restate.service({
  name: "billing",
  handlers: {
    async chargeCustomers(ctx: restate.Context, args: { planId: string; budgetUsd: number }) {
      // Fetch customers — deterministic, OK to replay
      const customers = await ctx.run("fetch-customers", async () => {
        const resp = await fetch(`https://your-api.run.app/customers?plan_id=${args.planId}`);
        return resp.json() as Promise;
      });

      // Fan-out: dispatch one child invocation per customer
      const client = ctx.serviceSendClient(chargeOneService);
      for (const customer of customers) {
        await client.chargeCustomer({ customerId: customer.id, amountCents: customer.amountCents });
      }
    }
  }
});

const chargeOneService = restate.service({
  name: "charge-one",
  handlers: {
    async chargeCustomer(ctx: restate.Context, args: { customerId: string; amountCents: number }) {
      await ctx.run("stripe-charge", async () => {
        // Full-access key: caps bind at account level, not per-invocation
        const intent = await stripe.paymentIntents.create({
          amount: args.amountCents,
          currency: "usd",
          customer: args.customerId,
        });
        return intent.id;
      });
    }
  }
});

The fan-out creates N concurrent chargeOneService invocations. Each invocation has independent access to the full-access Stripe key via the service environment variable. If customers returns 2,000 records due to a data issue, 2,000 simultaneous Stripe calls are dispatched with no per-invocation cap and no shared cap across the fan-out. Each child invocation is independent — if 500 of them exhaust what would be a budget, the remaining 1,500 proceed without knowing.

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

The ctx.run() memoization interaction with vault keys

Restate's ctx.run() is the exactly-once boundary: the first time the handler runs, the closure executes and the result is persisted in the journal. On any subsequent retry of the handler, ctx.run() returns the journaled result without re-executing the closure. This memoization property is essential for issuing vault keys correctly.

If you issue the vault key inside ctx.run("issue-vault-key", ...), the same vault key is returned on every retry of the handler — Restate re-reads the journal entry, not Keybrake. This means the cap accumulates correctly across retries: the second attempt to charge a customer doesn't start with a fresh cap, it continues counting against the cap set in the first handler execution. The vault key's TTL must cover the full expected handler duration including potential retry delays.

Scoping vault keys per Restate handler invocation

import * as restate from "@restatedev/restate-sdk";
import Stripe from "stripe";

const billingService = restate.service({
  name: "billing",
  handlers: {
    async chargeCustomers(ctx: restate.Context, args: { planId: string; budgetUsd: number }) {
      // Issue vault key once — memoized by Restate's journal on retries
      const { vaultKey } = await ctx.run("issue-vault-key", async () => {
        const resp = await fetch("https://proxy.keybrake.com/vault/keys", {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${process.env.KEYBRAKE_API_KEY}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            vendor: "stripe",
            daily_usd_cap: args.budgetUsd,
            allowed_endpoints: ["POST /v1/payment_intents"],
            expires_in: "2h",
            agent_run_label: `restate/billing/${ctx.request().id}`,
          }),
        });
        const data = await resp.json();
        return { vaultKey: data.vault_key };
      });

      // Fetch customers
      const customers = await ctx.run("fetch-customers", async () => {
        const resp = await fetch(`https://your-api.run.app/customers?plan_id=${args.planId}`);
        return resp.json() as Promise;
      });

      // Fan-out: pass vault key to each child invocation
      const client = ctx.serviceSendClient(chargeOneService);
      for (const customer of customers) {
        await client.chargeCustomer({
          customerId: customer.id,
          amountCents: customer.amountCents,
          vaultKey,  // shared across all children — shared cap
        });
      }
    }
  }
});

const chargeOneService = restate.service({
  name: "charge-one",
  handlers: {
    async chargeCustomer(
      ctx: restate.Context,
      args: { customerId: string; amountCents: number; vaultKey: string }
    ) {
      await ctx.run("stripe-charge", async () => {
        const stripe = new Stripe(args.vaultKey, {
          baseURL: "https://proxy.keybrake.com/stripe/v1",
        });
        const intent = await stripe.paymentIntents.create({
          amount: args.amountCents,
          currency: "usd",
          customer: args.customerId,
          idempotency_key: `${ctx.request().id}-${args.customerId}`,
        });
        return intent.id;
      });
    }
  }
});

The vault key is issued inside ctx.run("issue-vault-key", ...) so it is memoized: on handler retries, Restate returns the same vault key from the journal without issuing a new one. The vault key is passed explicitly to child invocations via the chargeCustomer input — all children share the same vault key and the same cap accumulates atomically across all concurrent child calls.

The idempotency key uses the Restate invocation ID (from ctx.request().id) plus the customer ID — stable across handler retries of the child invocation, unique across different handler runs. The Stripe client points at the Keybrake proxy with the vault key as the API key.

How Keybrake fits

Keybrake is the proxy layer between your Restate service handlers and Stripe, Twilio, or Resend. The vault key issued inside ctx.run() replaces the full-access STRIPE_SECRET_KEY environment variable. The real Stripe secret stays in Keybrake — never in Restate's journal (which stores ctx.run() results including the vault key, but the vault key is scoped, not the real secret). For Virtual Objects, use ctx.key() as part of the agent_run_label to correlate audit log entries with the specific object key and invocation. Revoking a runaway invocation is a single DELETE /vault/keys/{key_id} call — no Restate cancellation required, no environment variable rotation.

Get early access

Related questions

Further reading

• Inngest AI agent API key — similar durable function pattern with step memoization; Inngest's step.run() memoization is equivalent to Restate's ctx.run() for issuing vault keys exactly once.
• Temporal AI agent API key — Temporal Activities map to Restate ctx.run() closures; the vault-key-per-workflow-run pattern is equivalent across both frameworks.
• AI agent idempotency — why invocation-ID-based idempotency keys are essential when Restate retries handlers, and how to derive a stable key from the Restate request ID.
• AI agent multi-tenant isolation — when your Restate Virtual Objects serve multiple tenants (one object per tenant), per-tenant vault keys using ctx.key() ensure spending isolation between objects.