What a read-only Stripe restricted key can do

A read-only Stripe restricted key can list and fetch data from your account, and nothing else. It can't charge customers, refund, cancel subscriptions, create payouts or change any setting: Stripe answers any call that tries to with a permissions error. It can still see a lot, though, including your customers' names and emails if you give it read access to customers. You create one in the Dashboard under Developers, then API keys, choose Read or None for each resource, and expire it whenever you want.

Lots of tools ask for access to your Stripe account: analytics, dashboards, rankings like this one. Some ask for your secret key, which you shouldn't hand over when a restricted key can do the job. What follows is based on Stripe's docs on restricted API keys.

What kinds of Stripe keys are there?

• Publishable keys (pk_live_...) go in your frontend. They can only do what a browser needs, like creating a payment method. They're public by design.
• Secret keys (sk_live_...) can do everything your account can do through the API: charge customers, refund, cancel subscriptions, create payouts, delete things. Only your own server should ever have one.
• Restricted keys (rk_live_...) are secret keys with a list of permissions. For each resource (customers, subscriptions, invoices, charges and so on) you choose None, Read or Write. None is the default, and Write includes Read.

Each one also has a test version (pk_test_, sk_test_, rk_test_) that only works on test data.

What makes a key read-only?

A key where every permission is Read or None is a read-only key. Stripe maps reading to fetching and listing, and writing to anything that creates, changes or deletes. So a read-only key can list and fetch data, and any call that tries to charge, refund or change something comes back from Stripe with a permissions error, whatever the tool on the other end tries to do.

The check happens on Stripe's side, not in the tool. A tool with a buggy integration or bad intentions still can't write with a key that doesn't allow it. The error message even names the permission that's missing, which is also how a developer finds out what to ask for.

Restricted keys work with every Stripe API, so a tool that only needs to read never has a technical reason to ask for your secret key.

What can read access still see?

A read-only key still sees a lot. A key with Read on customers can see your customers' names, emails and billing details. A key with Read on charges can see amounts and the last four digits of cards (never full card numbers, Stripe doesn't hand those out to anyone).

So the questions to ask a tool aren't only "can it write" but also:

• Which resources does it ask to read, and why each one?
• Does it store what it reads, or ask Stripe each time?
• Where is the key stored, and how?
• What happens when you disconnect?

I'd want those answers in writing before connecting, not just the word "read-only".

How do you create one?

In the Stripe Dashboard, go to Developers, then API keys, and create a restricted key. Give it a name you'll recognize later (the name of the tool is best), set the permissions it needs to Read, and leave everything else at None. Stripe shows a live key once, when you create it. Paste it into the tool and don't keep a copy anywhere else.

Some tools give you a link that opens the form with the name and the permissions already filled in. Check them anyway before you create it: the form is Stripe's, so what you see there is what the key gets.

Make one key per tool. If two tools share a key, you can't cut off one without breaking the other.

How do you take it back?

On the same API keys page, the menu next to each key has "Expire key". Choose to expire it now and it stops working right away: the tool loses access without having to agree to anything.

There's also "Rotate key", which expires the key and creates a replacement with the same permissions. You can make the old one stop working now or after a delay of up to 7 days, which gives you time to paste the new key into the tool. Use it if a key may have leaked, or as a habit for keys you've had for a long time.

Is it safe to give one to a third party?

Much safer than a secret key, though there's still some risk. A read-only key can't move money or change your account, so the worst case is someone reading what the key can read. That's why the questions above matter, and why the permission list should be as short as the tool's job allows.

The key TrustChurn asks for

TrustChurn only accepts restricted keys. Secret keys are refused before they're saved, and the key needs Read access to a short list of resources (subscriptions, customers, invoices, prices and a few more), each one listed on our security page with why we need it.

The key is encrypted before it reaches our database, with an encryption key that lives outside it. We don't store your customers' names or emails: we ask Stripe for them when you open your private list. We don't register webhooks in your account, because that needs write access. Disconnecting deletes the key and everything we read with it.

With the same key you can run the scripts in how to calculate your churn from Stripe and finding scheduled cancellations yourself. If you want to see what the numbers look like before you trust us with anything, the ranking is public.

FAQ

Can a restricted key charge my customers?

Only if you gave it Write access to the resources that create charges. A key with only Read and None permissions can't create charges, refunds or payouts. Stripe rejects those calls with a permissions error.

Can a read-only key see full card numbers?

No. Stripe doesn't expose full card numbers through the API to anyone. With Read access to the right resources, a key can see details like the card brand, the last four digits and the expiry date.

How do I revoke a restricted key?

In the Dashboard, on the API keys page, open the menu next to the key and choose "Expire key". Expired now, it stops working right away.

What's the difference between a restricted key and a secret key?

A secret key can do anything your account can do through the API. A restricted key can only do what you allowed for each resource: None, Read or Write. A restricted key with only Read can't change anything.

Do test mode and live mode need different keys?

Yes. A live restricted key starts with rk_live_ and only works on live data. A test key starts with rk_test_ and only works on test data. A tool that shows your real numbers needs a live key.