The exact steps, including what the key can never do

Giving Recoverly read-only access to your Stripe account

This is the exact procedure to create the key we ask for, what that key lets us see, what it can never do, and how to switch it off.

It takes about five minutes. You need a Stripe user with permission to create API keys (an owner or administrator on the account).

Short version: In your Stripe dashboard, go to Developers → API keys → Create restricted key, name it Recoverly audit (read-only), set Invoices → Read and Charges → Read, leave everything else on None, click Create key, and send us the rk_live_… value through the same channel you received this link. Revoke it from the same page when you're done.

Direct link: https://dashboard.stripe.com/apikeys (Test mode, if you'd rather practise on test data first: https://dashboard.stripe.com/test/apikeys)


1. Create the key, step by step

  1. Sign in to Stripe and open https://dashboard.stripe.com/apikeys.
  2. Find the Standard keys panel.
  3. Click Create restricted key.
  4. Give it a name you'll recognise later, e.g. Recoverly audit (read-only). Naming it matters: it's how you'll find it on this page to revoke it.
  5. Set the permissions. Use the dropdown next to each resource:

    ResourceSet it toWhy
    InvoicesReadThe audit's only source of figures. This is the one that matters.
    ChargesReadThe failed charge behind an invoice often carries the decline code. Without this, some invoices are reported as "unknown" instead of classified.
    AccountRead (optional)Only so the page can print your account's name. Without it the audit says it couldn't read the name and carries on — no figure changes.
    everything elseNoneLeave Customers, Subscriptions, Payment Intents, Products, Prices, Payment Methods, Payouts, Balance, Webhook endpoints, Files … all on None.
  1. Click Create key.
  2. Stripe shows the key once — it starts with rk_live_ (or rk_test_ in test mode). Copy it, and note that nobody, including Stripe support, can show it to you again. If you lose it, create another one and revoke this one.
  3. Send it to us through the same channel you received this link — ideally a one-time link from a password manager that expires after a single view. Please don't paste it into an open chat, a shared document, a screenshot, or a public form field.

That's it. There is nothing to install, no OAuth dance, and no Stripe Connect application.

2. What we can read with that key

Exactly this, and nothing else:

  • Invoices: status, amount due, amount still owing, amount paid, currency, the customer id and email on the invoice, the subscription id, the attempt count, the next scheduled retry, the hosted invoice URL, creation and due dates, and the decline code Stripe recorded on the invoice or on its failed charge.
  • Charges: whether the charge behind an invoice failed, and the failure / decline code on it. (Charges Read is also what lets the audit ask Stripe "which charge failed for this invoice?" when the invoice itself doesn't say.)
  • Account (only if you granted it): your account id and its display name.

With the two-resource key above we cannot read your customers' saved records, your subscriptions, your products or prices, your payment methods, your balance, your payouts, your disputes, or your other API keys. Card numbers and CVCs are never returned by Stripe's API to any application, including ours, at any permission level.

3. What the key can never do

A restricted key with Read only cannot:

  • create, capture, refund or cancel a charge or a payment;
  • change an invoice, a subscription, a customer, a price or a payment method;
  • retry a payment;
  • move money, change payouts, or change account settings;
  • read any Stripe account other than the one it was created on.

If you'd rather verify than trust: give it to us in test mode first (https://dashboard.stripe.com/test/apikeys). The audit will read your test invoices and print a page from them; nothing in live mode is touched. The page says which mode it read.

If we ever need more than read. A pilot needs exactly one permission beyond the two above: write access on Invoices — the one that lets us attempt collection on a failed invoice (POST /v1/invoices/{id}/pay). Stripe's restricted keys work per resource, as None, Read or Write, so we do not need anything else, and Charges → Read stays exactly as it is.

We name that scope in writing, and you confirm it in your own dashboard before it is granted. The request tells you the exact scope to switch on; if what your Stripe dashboard offers is named differently from what this page calls it, the written request is what counts, and you can refuse it. We have not asked any client for it yet.

We ask for that one permission separately and in writing, with the permission named, and only after you have seen the audit and decided to run a pilot. The key you create for the audit stays read-only; it never gains a write permission without a fresh, written request from us that you can refuse.

4. Check we did what we said

  • The key's Last used column on the API keys page tells you when we last used it.
  • Developers → Logs (in newer dashboards, under Workbench → Logs) shows the API requests made against the account, including which key made them and which endpoint was called. You should see only GET requests for invoices, charges and account — never anything that writes.
  • The audit page itself states how many read requests it made, the API version it pinned, and that nothing was written to your account. If that ever disagrees with your logs, the logs are right and we will want to know.

5. Revoking it

Do this whenever you like — after the audit, after a pilot, or on a hunch. It takes effect immediately.

  1. Go to https://dashboard.stripe.com/apikeys.
  2. Find the key named Recoverly audit (read-only) under Standard keys.
  3. Either:

    • Delete it (the menu on the key's row) — the key stops working at once, and the name disappears from the list; or
    • Roll it — Stripe issues a new value and the old one stops working at once. Rolling is the better choice if you might want us to audit again later: tell us the new value and access continues.
  4. If you asked us to read in test mode as well, revoke the test-mode key under https://dashboard.stripe.com/test/apikeys too — live and test keys are separate lists.

Revoking does not touch anything we already produced: the audit page you received stays as it is. It does mean we can no longer read your account, which is exactly the point.

6. What not to send

  • A live secret key (sk_live_…). It can move money, and the audit will refuse it rather than hold it. Our command prints the reason and reads nothing.
  • A publishable key (pk_…). Safe to publish, but it can't list invoices, so every read would be rejected.
  • Your Stripe password, a login link, or a 2FA code. Nobody at Recoverly will ever ask for these.
  • A key with Write permissions on anything, unless you have separately agreed a pilot with us and we have asked for a specific write permission in writing.

If in doubt: send the restricted key, and check the Last used column and your Logs afterwards. If you see anything other than reads of invoices, charges and account, revoke the key and tell us — that would be a fault on our side and we would want it on the record.

Questions this page doesn't answer?

The free leak audit itself — what it returns, what it can't see, and what we can't recover — is described on the main page. To ask before you hand anything over, use the audit form and say you only want the question answered, or write to [email protected].