How to make a read-only Stripe restricted key
Last updated 12 October 2026
Most tools that work with your Stripe data need an API key. Give them a restricted key (rk_…) that can only read, never your secret key (sk_…). A secret key can do anything your account can, including moving money. Stripe’s own rule is that third-party tools must not ask for one. A tool that does is one to be wary of.
Make the key
- Open Stripe → API keys.
- Click Create restricted key.
- Name it after the tool it’s for, so you know later which key to revoke.
- Set Read on each resource the tool needs and leave everything else at None.
- Create it, copy it and paste it into the tool.
A key made in a sandbox starts rk_test_ and sees only test data; one made in live mode starts rk_live_. Each Stripe account has its own keys, so a business with three products makes three.
Which permissions
Only what the tool reads. For example, here is what Gradsey asks for, and what each one is read for:
| Read on | Used for |
|---|---|
| Subscriptions | Who is cancelling, failing to pay or renewing, and their plans and coupons. |
| Customers | Names and email addresses, so every row is someone you can write to. |
| Invoices | Amounts due, payment attempts and the links customers pay on. |
| Products | Plan names, so a row says “Pro”, not a price id. |
| Events | This month’s changes to subscriptions, such as a cancellation being reversed. |
| PaymentIntents | Why a card was declined: the decline code and Stripe’s advice. |
| Charges | Refunds, so money handed back isn’t counted as saved. |
| Test clocks | Sandbox keys only: subscriptions on a test clock are missing from Stripe’s ordinary lists. |
If a tool asks for Write on anything, ask why. Reading doesn’t need it.
What a read-only key can and can’t do
It can’t charge a card, refund a payment, cancel a subscription or change a price. Every one of those is a write, and Stripe turns it away. It can still read what you gave it, and that includes your customers’ names and email addresses. So ask how the tool stores the key and what it keeps from each read.
Gradsey encrypts the key before storing it and never shows it back in full, only its last few characters. It encrypts every customer name and email it keeps too. The privacy page lists everything else.
Check it before you rely on it
A key missing one permission still works for everything else, so the gap shows up later, as a report that is quietly empty. A good tool tries each permission before it stores the key and tells you which are missing. Gradsey does one small read per permission when you paste a key, names any that are missing by their name in the Dashboard, and doesn’t save the key until they all work. It works the same on an empty sandbox: a refused permission doesn’t depend on there being any data.
Taking it back
You can delete a restricted key in Stripe → API keys at any time, and the tool loses access at once. Delete one you no longer use rather than leaving it around. In Gradsey, removing a key under Profiles deletes the key, its stored scan and your marks for it at the same moment.