Stripe Restricted API Keys: A Security Guide for Publishers

A Stripe restricted API key is a server-side key, starting with rk_live_ or rk_test_, that can only do what you allow, resource by resource, with None, Read or Write permissions. When a third-party tool needs access to your Stripe account—such as an ad booking tool that creates payment pages and captures payments—give it a restricted key with the minimum permissions it needs instead of your all-powerful secret key.

Key takeaways

• A secret key can do anything in your Stripe account; a restricted key can only do what you allow, and Stripe recommends restricted keys for most uses.
• Give each tool its own key with the smallest set of permissions; Write includes Read.
• A live restricted key you create is shown only once, so store it safely the moment you create it.
• Rotate a key when someone with access leaves or when it may have leaked; a Dashboard rotation can keep the old key working for up to 7 days.
• Create and test the key in a sandbox first, then create a matching live key.

Stripe's key types in plain English

Stripe's API keys documentation is direct about this: because you can't limit a secret key's permissions, Stripe doesn't recommend secret keys for new use cases and suggests moving existing usage to restricted keys. Webhook signing secrets are a separate thing—they verify that incoming events came from Stripe and aren't API keys at all.

Why restricted keys matter when you use third-party tools

Every tool you connect to Stripe is a place where your key could leak: a breached server, a careless log file, a support ticket with a screenshot. If that key is a secret key, whoever finds it can do anything your account can do. If it's a restricted key, they're limited to its permissions.

Stripe's own example: a key that can only read dispute data can't create charges, access customer payment methods or trigger payouts, even in the wrong hands. For a publisher, that's the difference between an inconvenience and a disaster.

Which permissions does an ad booking tool need?

Exact requirements vary by tool, so always follow the tool's own list. A typical ad booking flow touches these resources:

Two notes. First, Write includes Read, so you never need to grant both. Second, Webhook Endpoints is a sensitive permission because it lets the key subscribe to events across your whole account—grant it only to tools you trust with that job.

If a tool fails because a permission is missing, Stripe returns an error that explains which permission to add. You can also open the key's request logs from the API keys page: GET requests are reads, while POST and DELETE requests are writes.

How to create a restricted key

Following the steps in Stripe's restricted key guide:

1. Open the API keys page in the Stripe Dashboard. Check which mode you're in: a sandbox for testing, live mode for real payments.
2. Click Create restricted key. You can start from zero permissions or from a preconfigured set.
3. Name the key after the tool and environment, for example "ad-booking-live."
4. Set each resource to None, Read or Write. Everything starts at None.
5. Click Create key and complete the two-factor verification.
6. Copy the key value and store it immediately. You can't retrieve it later.
7. In the note field, record where the key is used, then paste it into the tool.

To change permissions later, open the key's menu and choose Edit key. To make a similar key, use Duplicate key.

Test keys vs. live keys

Sandbox keys (rk_test_) work only with test data; live keys (rk_live_) work only with real data. Objects don't cross over, so a product created in a sandbox can't be used in a live payment.

The safe order is:

1. Create a restricted key in a sandbox and connect it to the tool.
2. Run test bookings with test cards, including approvals, rejections and refunds.
3. Create a live key with the same permissions and swap it in.

In a sandbox you can reveal your keys at any time. In live mode, a key you created yourself is shown once, which is why the note field matters.

Rotate, expire and revoke keys

Rotate a key when a team member with access leaves, when you suspect a leak, when you've lost the value, or on a regular schedule. Rotating revokes the key and generates a replacement that works immediately. In the Dashboard you choose when the old key expires: pick Now if the key may be compromised, or a later time so the old and new keys both work for up to 7 days while you update the tool.

Expire a key when you stop using a tool. Expiry takes effect immediately, and anything still using the key stops working, so disconnect the tool first.

If a restricted or secret key is ever exposed—in a public repository, a log file or an email—Stripe's advice is to rotate it immediately, even if you aren't sure anyone saw it.

Security habits that take five minutes

Stripe's key best practices boil down to a handful of habits that apply to any publisher:

• One key per tool. If one tool is compromised, you rotate one key and nothing else breaks.
• Never share keys over email or chat. Stripe never asks for your secret API key.
• Store keys in a password manager or secrets vault, never in code or a shared document.
• Use access policies where you can. Stripe can block requests that don't come from allowed IP addresses, networks or countries; this works when a tool publishes the server addresses it uses.
• Check request logs now and then, and look for activity you don't recognize.
• Review permissions quarterly and remove anything a tool no longer uses.

Connecting a booking tool safely

When you connect Spreadiom, you paste in your Stripe API keys, and a restricted key is recommended. Keys are stored encrypted, and the Stripe webhook is created for you automatically, so the key needs permission to manage webhook endpoints alongside the payment permissions. Test mode is supported, so you can connect sandbox keys, run a test booking and then switch to live keys. Create a free account when you're ready. For the payment flow itself, see accepting advertising payments with Stripe and authorize-then-capture ad payments.

FAQ

What is the difference between a Stripe secret key and a restricted key?

A secret key has unrestricted access to every Stripe API in your account, so anyone holding it can do anything your account can do. A restricted key only has the permissions you assign, resource by resource, as None, Read or Write. Both must stay on servers and never appear in browser code, but a leaked restricted key does far less damage.

Which Stripe permissions does an ad booking tool need?

It depends on the tool, so follow its documentation. A typical booking flow needs Write on Checkout Sessions to create payment pages and Write on Payment Intents to capture or cancel held payments. It may need Read or Write on Charges and Refunds, plus Write on Webhook Endpoints if it creates its own webhook. Everything else, including payouts and transfers, can usually stay at None.

What should I do if my Stripe API key leaks?

Rotate it immediately from the API keys page, choosing to expire the old key now rather than later, and paste the replacement into the tool that uses it. Then check the key's request logs for activity you don't recognize and review recent payments, refunds and payouts. Stripe treats any exposure as a potential compromise, even if you aren't sure anyone used the key.

Can I see my restricted key again after creating it?

Not in live mode. Stripe shows a live restricted key you created yourself only once, at creation, and can't recover it if you lose it. If that happens, rotate or expire the key and create a new one. Sandbox keys are different: you can reveal them at any time. Use the key's note field to record where you stored it.

Do I need separate keys for test mode and live mode?

Yes. Sandbox keys start with rk_test_ and only work with test data, while live keys start with rk_live_ and only work with real payments. Create and test the restricted key in a sandbox first, confirm every step of the booking flow works, and then create a live key with exactly the same permissions for production.