Keybrake

Stripe Restricted Keys

How to get a Stripe restricted API key

Four steps, three minutes, and three preset scope sets for the AI-agent use cases we see most often.

TL;DR

In the Stripe Dashboard: Developers → API keys → Create restricted key. Name it after the agent's role and runner ID, tick only the minimum permissions, and copy the rk_live_… key to your secret store on the one-time reveal screen. Use test mode first.

Step 1 — Open the API keys page

Sign in to the Stripe Dashboard. In the left-hand navigation, click Developers. Then click API keys in the Developers submenu.

If you are in test mode (toggle in the upper right), you will see rk_test_…-prefixed keys. If you are in live mode, keys are rk_live_…. We strongly recommend creating and testing in test mode first, then recreating the equivalent key in live mode only once the agent is exercising the expected 401s on out-of-scope calls.

Step 2 — Create the key

Scroll past the Standard keys section. In Restricted keys, click Create restricted key.

Name the key specifically. A good pattern:

agent-<role>-<action>-<runner-id>
  e.g. agent-support-refunds-runner42
       agent-catalog-updates-runner-beta
       agent-invoicing-finalize-runner-prod-03

The name is the only signal you will have later in audit logs and in the API-keys list. "Agent key #3" is not a useful name at 2 a.m. on Tuesday when you are figuring out which agent started the refund loop.

Step 3 — Pick the minimum scope set

Every resource row offers None, Read, or Write. Default everything to None and then enable the minimum set for the agent's actual job. Three scope presets we see most often:

Preset A — Refund-only support agent

The agent reads tickets and issues refunds. Cannot create charges, touch subscriptions, or change customers.

Charges         → Read
PaymentIntents  → Read
Customers       → Read
Refunds         → Write
# everything else → None

Preset B — Read-only reconciliation agent

The agent reads the ledger and builds reports. Writes nothing back to Stripe.

Charges               → Read
PaymentIntents        → Read
Customers             → Read
Invoices              → Read
Balance Transactions  → Read
Events                → Read
Payouts               → Read
# everything else → None

Preset C — Catalog-update agent

The agent syncs product catalog with the e-commerce system. Does not touch money or customers.

Products  → Write
Plans     → Write
Prices    → Write
# everything else → None

Step 4 — Copy the key once

Click Create key. Stripe displays the full key on the next screen. This is the only time you will ever see the full string. Copy it directly into your secret store — 1Password, AWS Secrets Manager, Vault, Doppler, whatever your team uses. Do not paste it into Slack or a ticketing system.

If you close the browser tab before copying, you cannot recover the key. You have to delete the (invisible) key from the dashboard and create a new one.

After you have the key

  1. Store it with a label that matches the key name. Not "Stripe key" — the same role-action-runner label you used in the Dashboard. Future-you will thank you.
  2. Test against test mode first. Point the agent at the test key and run the workflow end-to-end. Every out-of-scope call should return 401. Any 200 on an endpoint you didn't tick means your scope set is wrong.
  3. Set up a key-rotation reminder. Restricted keys don't expire automatically. Rotate on a schedule (90 days is reasonable for production) or whenever a runner leaves the fleet.
  4. Decide how you'll revoke mid-run. If the agent gets stuck, how does an on-call engineer stop it in under a minute? The Dashboard takes longer than that.

What Restricted Keys don't cover

Three problems that remain after you've picked the perfect scope set:

See the full permissions map with runaway-risk annotations per resource.

How Keybrake helps

Keybrake wraps your Restricted Key with the three things it can't do alone: per-day USD caps per resource, a customer allowlist, and a kill-switch that takes effect on the next call (typically under a second). You keep the Restricted Key as the upstream. Your agents call Keybrake with a scoped vault key. See the feature matrix →

Get early access

Related questions

Do Restricted Keys work in test mode?

Yes — toggle to test mode in the upper right of the Dashboard, and the same Create restricted key flow produces an rk_test_… key. Test keys operate on Stripe's test data only and cannot move real money.

Can I reveal a Restricted Key again after I close the tab?

No. Stripe shows the full key exactly once. If you lose it, delete the (invisible) key from the Dashboard and create a new one. The deleted key's row will persist in your API-keys list for a week or so before it disappears.

Can I restrict the key to my own IP range?

Not via the Dashboard Restricted Key UI. Some Stripe accounts have access to IP allowlisting on Standard keys via their account rep. For Restricted Keys, IP allowlisting is not a native feature.

How do I rotate a Restricted Key?

Create a new Restricted Key with the identical scope set, update your secret store to point to it, deploy, then delete the old one from the Dashboard. There is no "rotate" button — rotation is a create-then-delete pattern.

Further reading