Stripe restricted keys: how to create a safe read-only key

What a restricted key is

Stripe issues three kinds of API key, and the difference matters more than the prefixes suggest.

The sentence worth quoting from Stripe's documentation is about secret keys: because their permissions cannot be limited, Stripe does not recommend them for new use cases, and recommends migrating existing integrations from secret keys to restricted ones. If a tool asks you for an sk_ key in 2026, that is a question worth asking them about.

Keys also come in sandbox and live flavours. Sandbox keys start with pk_test_, rk_test_ and sk_test_; live keys with pk_live_, rk_live_ and sk_live_. Objects created in one mode are invisible in the other, so a test key will never show you real revenue.

Creating a read-only key, step by step

The flow gained two questions recently, and neither is obvious. Pick the wrong permission template and you never reach the screen where you set individual permissions.

1. 1.In your Stripe dashboard, go to Developers, then API keys.
2. 2.Click Create restricted key.
3. 3.When asked how you will use the key, pick Power an integration you built.
4. 4.For the permission template, pick Choose your own, at the bottom of the list.
5. 5.Set only the permissions the tool actually needs to Read, and leave every other permission on None.
6. 6.Create the key, copy it — it starts with rk_ — and paste it where it is needed. Save it somewhere safe: a key you create yourself in live mode cannot be revealed again after you close the dialog.

That last point catches people. In live mode, Stripe can only re-reveal keys it generated for you. If you created the key yourself and lose it, there is no recovery — you rotate or expire it and make a new one.

What a read-only key can and cannot do

Our own audit asks for three permissions, all set to Read: Invoices, Subscriptions and PaymentIntents. That is a useful example because it is close to the minimum any failed-payment tool needs.

• Invoices, read: see which invoices were issued, which were paid, and how many payment attempts each one took.
• Subscriptions, read: see which subscriptions were cancelled and when, which is how an unpaid invoice gets linked to a lost customer.
• PaymentIntents, read: see why a charge was refused, because the decline code lives on the payment intent rather than on the invoice.

With those three on Read and everything else on None, the key cannot charge a card, issue a refund, change a price, create a payout, read your bank details or modify a subscription. Hand it to a tool and the worst it can do is look.

This also gives you a test for any tool asking for access: ask which permissions it needs and why. A recovery product that retries payments genuinely needs write access — you cannot retry a charge with a read-only key. A product that only reports should never need more than Read.

It is still a secret

Restricted does not mean harmless, and Stripe says so directly: only publishable keys are safe to expose outside your backend, and you remain responsible for protecting restricted keys as well. A read-only key over your billing data is a read-only key over your customer list.

• Do not paste keys into email, chat or any unencrypted channel. Stripe's documentation names this explicitly.
• Do not commit keys to source control or configuration files. Use a secrets vault, or environment variables if your platform has none.
• Consider an access policy on live keys, which can restrict use to specific IP addresses, or by autonomous system number and country, and block traffic from Tor exit nodes, public proxies and anonymous VPNs.
• Rotate keys when someone with access leaves, and whenever you suspect exposure.

For what it is worth, this is why our audit holds your key in an encrypted cookie in your own browser for two hours at most and never writes it to a database or a log. It is also why the honest advice at the end of an audit is to revoke the key, not to leave it lying around in case you want another one.

Revoking and rotating

Taking a key back takes about fifteen seconds, and you do not need the cooperation of whoever you gave it to.

1. 1.Open the API keys page in your dashboard.
2. 2.Find the key in the Restricted keys list and open its overflow menu.
3. 3.Choose Expire key. Any code still using it stops working immediately.

If you need continuity rather than a clean break, rotate instead. Rotating from the dashboard keeps the old and new key working together for up to seven days, which is enough to migrate services gradually. Stripe's own advice is to watch the old key's request logs and only expire it once its volume has sat at zero for a while.

One oddity worth knowing: a key's access can be limited automatically if it has not been used for transfers, payouts or payout-destination updates in more than 180 days. You can restore it from the same overflow menu.

Questions people ask

What is a Stripe restricted key?

An API key starting with rk_ whose permissions you set yourself, resource by resource, with read or write levels. Stripe recommends creating as many as you need and giving each part of an integration its own, so that a leaked key limits the damage.

Is a restricted key safe to give to a third-party tool?

Safer than a secret key, which has unlimited permissions and cannot be narrowed. It is still a secret: Stripe states that only publishable keys are safe to expose, and that protecting restricted keys remains your responsibility. Grant the minimum permissions, and expire the key when the tool no longer needs it.

How do I make a read-only Stripe key?

Developers, then API keys, then Create restricted key. Choose Power an integration you built, then the Choose your own permission template, then set only the resources you need to Read and leave everything else on None.

How do I revoke a Stripe key?

On the API keys page, open the key's overflow menu and choose Expire key. It stops working immediately. If you need a transition period instead, rotate it: the old and new keys both work for up to seven days.

Why does a tool need write access to my Stripe account?

If it retries failed payments, emails customers a card-update link, or changes subscriptions, it has to write. A tool that only reports on your data should never need more than read permissions, and it is reasonable to ask one that does.

Sources

• Stripe Docs — API keys — checked 7 October 2026
• Stripe Docs — Restricted API keys — checked 7 October 2026
• Stripe Docs — API key best practices — checked 7 October 2026