Temporal AI agent API key: scoping activity calls to Stripe and Twilio

How Temporal AI agents call vendor APIs

In a Temporal workflow, the actual API calls happen inside activities — ordinary functions decorated with @activity.defn (Python) or implemented as plain async functions (TypeScript/Go). The workflow orchestrates which activities run and in what order; the activities do the work.

A billing workflow built on Temporal might look like:

# Python / temporalio SDK
@activity.defn
async def charge_customer(customer_id: str, amount_cents: int) -> dict:
    stripe.api_key = os.environ["STRIPE_SECRET_KEY"]  # real key, full access
    return stripe.PaymentIntent.create(
        amount=amount_cents,
        currency="usd",
        customer=customer_id,
    )

@workflow.defn
class BillingWorkflow:
    @workflow.run
    async def run(self, params: BillingParams) -> None:
        for invoice in params.invoices:
            await workflow.execute_activity(
                charge_customer,
                args=[invoice.customer_id, invoice.amount_cents],
                start_to_close_timeout=timedelta(seconds=30),
                retry_policy=RetryPolicy(maximum_attempts=3),
            )

This is solid Temporal code. The retry policy, durable execution, and workflow history are all working correctly. The problem is the API key: STRIPE_SECRET_KEY is a long-lived, full-access key with no per-workflow cap and no way to revoke access for just this workflow run without affecting everything else using that key.

Three gaps Temporal's native tooling doesn't fill for vendor API calls

The retry risk: why Temporal makes this worse than a script

Temporal's automatic activity retries are a feature — until a vendor API call is the activity that's retrying. Consider what happens when a Stripe charge activity fails with a 500 (Stripe's server error) on the first attempt:

1. Temporal schedules a retry (correct behavior).
2. The activity runs again and succeeds — but if the first attempt actually went through on Stripe's side before returning 500, you've now created two charges.
3. Stripe's idempotency keys solve the duplicate-charge problem if you pass the same key on retry — but many teams don't wire this up correctly, and even when they do, the idempotency key has to be stable across retries, which requires passing it through from the workflow context.

This is a known problem. The vault key proxy adds a second layer: even if a retry would double-charge, the per-workflow spend cap catches it. If the cap is $500 and the workflow has already successfully processed $400 of charges, a retry-triggered double-charge will hit the cap and return a 429 instead of completing. Your error handling catches the 429, you investigate, and you don't have a refund problem.

Scoping vault keys per workflow run in Temporal

The vault key is issued once per workflow run — in the workflow code before the first activity, or in a dedicated setup_activity. It travels through the workflow via the activity context or a shared parameter:

# Python / temporalio SDK
import httpx

@activity.defn
async def issue_vault_key(workflow_id: str, budget_usd: float) -> str:
    async with httpx.AsyncClient() as client:
        r = await client.post(
            "https://proxy.keybrake.com/vault/keys",
            headers={"Authorization": f"Bearer {os.environ['KEYBRAKE_API_KEY']}"},
            json={
                "vendor": "stripe",
                "daily_usd_cap": budget_usd,
                "allowed_endpoints": ["POST /v1/payment_intents", "GET /v1/customers/*"],
                "expires_in": "8h",
                "agent_run_label": f"temporal-billing/{workflow_id}",
            },
        )
        return r.json()["vault_key"]

@activity.defn
async def charge_customer(customer_id: str, amount_cents: int, vault_key: str) -> dict:
    stripe.api_key = vault_key           # scoped key, not the real secret
    stripe.api_base = "https://proxy.keybrake.com/stripe"
    return stripe.PaymentIntent.create(
        amount=amount_cents,
        currency="usd",
        customer=customer_id,
        idempotency_key=f"{activity.info().workflow_id}-{customer_id}-{amount_cents}",
    )

@workflow.defn
class BillingWorkflow:
    @workflow.run
    async def run(self, params: BillingParams) -> None:
        vault_key = await workflow.execute_activity(
            issue_vault_key,
            args=[workflow.info().workflow_id, params.budget_usd],
            start_to_close_timeout=timedelta(seconds=10),
            retry_policy=RetryPolicy(maximum_attempts=2),
        )
        for invoice in params.invoices:
            await workflow.execute_activity(
                charge_customer,
                args=[invoice.customer_id, invoice.amount_cents, vault_key],
                start_to_close_timeout=timedelta(seconds=30),
                retry_policy=RetryPolicy(maximum_attempts=3),
            )

The vault key is now per-workflow: each workflow run gets its own scoped key with its own dollar cap. The proxy logs every call with agent_run_label: "temporal-billing/{workflow_id}", so you can query the Keybrake audit log filtered by workflow ID and see the exact charges made by that run — not just Temporal's event log, but the actual amounts from Stripe's responses.

Long-running workflows: the compounding risk

Temporal is designed for workflows that run for minutes, days, or months. A subscription renewal workflow that fires every 30 days, a customer onboarding workflow with a 14-day trial check-in, or an AI agent workflow that waits for external events and then charges — all of these accumulate Stripe calls over time that no one is actively watching.

The per-workflow vault key approach handles this naturally: you set the daily_usd_cap at workflow start time based on the expected spend, and the proxy enforces it every day the workflow runs. If the workflow is supposed to charge at most $1,000/day and it starts approaching that (whether due to a bug, unexpected data volume, or a malicious input), the cap fires and the workflow receives a 429 that your error handling can route to a human-review queue or a Temporal signal.

How Keybrake fits

Keybrake is the proxy layer between your Temporal activities and Stripe, Twilio, or Resend. You swap stripe.api_key for the vault key and set stripe.api_base to https://proxy.keybrake.com/stripe. The real Stripe secret stays on the Keybrake side, never in your activity environment. Each workflow run gets its own vault key with its own spend cap, endpoint allowlist, and expiry. The audit log stores every call with the workflow ID label you set at key-issue time — queryable via the Keybrake dashboard or REST API.

Get early access

Related questions

Further reading

• AI agent kill switch patterns — the four ways to stop a runaway agent and their real stop latencies, including mid-workflow scenarios.
• AI agent audit trail schema — what belongs in a structured per-call log and the SQL queries that matter when reviewing a billing incident.
• AI agent cost management — the full cost map: LLM spend, SaaS tool spend, and infra spend — which tool handles which.
• AI agent Stripe spend cap — a deep dive on why pre-charge enforcement beats post-charge alerts for stuck agent loops.