Stripe test-mode discipline for automated agents: restricted keys and test clocks

TL;DR

Before any Stripe work, check the key prefix. Stripe lets you create restricted API keys with a chosen subset of permissions, in both test and live mode.

When to use

You are seeing this: Agents are fast, literal, and have no fear. Use this skill when you run into "Stripe test-mode discipline for automated agents: restricted keys and test clocks".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Stripe test-mode discipline for agents

Agents are fast, literal, and have no fear. That combination near payment APIs needs guardrails, not trust.

1. Live keys never enter agent context

Test secret keys start with sk_test_. Restricted keys start with rk_test_ or rk_live_. Before any Stripe work, check the key prefix. If it starts with sk_live_ or rk_live_, stop and ask the operator. No exceptions, no "just this once".

2. Restricted keys with least privilege

Stripe lets you create restricted API keys with a chosen subset of permissions, in both test and live mode. From the docs: "Using a restricted API key with only a subset of API permissions limits the damage a bad actor could cause if they obtained the key."

For agent work, mint a restricted test key with only what the task needs:

• Read-only exploration: read permissions only.
• Building a checkout flow: write on PaymentIntents and Customers, nothing else.
• Never hand an agent the account's full secret key. The full key is for the operator's Dashboard session, not for automation.

3. Test clocks for time-dependent logic

Subscriptions, trials, and invoices depend on time passing. Test clocks freeze and advance time for test objects so you can verify billing behavior without waiting days.

• Create a test clock, attach the test customer to it.
• Advance the clock to simulate trial end, renewal, dunning.
• Verify invoices and subscription states at each step.
• Delete the clock when done.

This is how you test "what happens when the trial ends" in minutes instead of 14 days.

4. Separate everything

Test mode and live mode are separate worlds: separate keys, separate customers, separate webhook endpoints. An ID from test mode means nothing in live mode. Never copy IDs across the boundary.

The one-line policy

Agents touch test mode with restricted keys. Live mode is operator territory.

Stripe's authentication docs: test secret keys start with sktest and "have unrestricted access to their sandboxes"; restricted API keys (rktest / rklive) are configured "with specific API permissions" and "limits the damage a bad actor could cause if they obtained the key" (docs.stripe.com/api/authentication, linking to /keys#create-restricted). The API reference documents Test Clocks with frozentime and an "Advance a test clock" operation (docs.stripe.com/api/testclocks). Agents cannot distinguish key types by intent, so prefix checks and least-privilege keys are the guardrail. Verified against live docs 2026-09-26.