Connect Stripe to FlowMRR: access, permissions and webhooks
The two ways to connect, exactly what each one lets us do, and how to register the webhook yourself if your key can't.
FlowMRR reads your Stripe account to compute MRR, churn, cohorts and recovery. There are two ways to give it access — 'Connect with Stripe' (OAuth) or pasting an API key — and they behave differently on one point that matters: real-time updates via webhooks. This guide explains both paths, lists the precise permissions involved, and shows the manual fallback when a restricted key cannot create a webhook endpoint on your behalf.
Step 1
Choose your connection method
'Connect with Stripe' sends you to Stripe, you approve FlowMRR, and Stripe hands us an access token — nothing to copy, revocable from your Stripe Dashboard at any time, and real-time updates work immediately because we receive your events on our platform's Connect endpoint. Pasting an API key gives you fine-grained control over what the key can do, at the cost of managing the key yourself. Both produce the same analytics.
Tip
If you're not sure, use 'Connect with Stripe'. It is the standard model for Stripe integrations and the one with the fewest moving parts.
Step 2
What 'Connect with Stripe' grants — and why it says read-write
Stripe's Connect OAuth for standard accounts only offers one scope, read_write; Stripe does not make a read-only option available to platforms like ours. FlowMRR uses that access almost exclusively to read: customers, subscriptions, invoices, products, coupons, charges, refunds, disputes and balance. The single write we ever perform is Invoice.pay — retrying a failed invoice — and only when you click 'Retry payment' on the Recovery page. We never create, edit or delete anything else on your account.
Watch out
The Stripe consent screen will say FlowMRR can 'manage' your account. That is Stripe's generic wording for the read_write scope; our actual behaviour is described above and in our data commitments page.
Step 3
Building a restricted API key (recommended for the key path)
In Stripe Dashboard → Developers → API keys → 'Create restricted key'. Grant Read on: Customers, Subscriptions, Invoices, Products, Coupons, Charges, Refunds, Disputes, Payment Intents, Payment Methods, Balance and Balance transactions (or simply 'All core resources' and 'All Billing resources' as Read). Then grant Write on exactly two: Invoices (so 'Retry payment' works) and Webhook Endpoints (so FlowMRR can register its own webhook). Name the key 'FlowMRR' so you recognise it later, copy it once — Stripe won't show it again — and paste it into FlowMRR.
Tip
You can rotate this key at any time: create a new restricted key, paste it in Settings → Stripe, then delete the old one in Stripe. FlowMRR swaps the credential without re-syncing from scratch.
Step 4
Using a read-only key: what you give up
A read-only key is perfectly fine for analytics — every dashboard, cohort and forecast works. Two things stop working: 'Retry payment' on the Recovery page (it needs Invoices: write), and automatic webhook registration (it needs Webhook Endpoints: write). Without a webhook, FlowMRR still refreshes your data on its scheduled sync every few minutes, so nothing is lost — it just isn't live. The Recovery page tells you explicitly when your key can't retry payments, and Settings → Stripe shows the manual webhook option described next.
Step 5
Registering the webhook manually
Open FlowMRR → Settings → Stripe. If your key cannot create endpoints you'll see 'Register the webhook manually' with an endpoint URL and a list of events. In Stripe Dashboard → Developers → Webhooks → 'Add endpoint': paste the URL, select exactly the listed events (customer.subscription.*, invoice.*, product.*, price.*, coupon.*, charge.refunded, charge.dispute.created), and create it. Stripe then shows a signing secret starting with whsec_. Copy it into the FlowMRR field, optionally with the endpoint id (we_…), and save. The connection status flips to 'Real-time updates active'.
Watch out
Select the events from the list FlowMRR shows you rather than 'all events'. Extra events are harmless but they inflate your Stripe webhook logs and our processing for no benefit.
Step 6
Verifying everything works
Settings → Stripe shows three things: the connection status (key valid, live vs test mode), the webhook status, and the last sync. Run a sync once after connecting; when it completes, make a small change in Stripe — update a coupon, for instance — and watch it appear in FlowMRR within seconds if webhooks are working. If the badge says 'test mode', you connected a test-mode credential: reconnect with a live one.
Step 7
Pausing, revoking and deleting
You stay in control at every step. Pause stops all ingestion while keeping your data frozen at that moment. 'Remove credentials' deletes the token or key from our systems (and, for API keys, removes the webhook we created), optionally erasing every synced row. For Connect, revoking FlowMRR from your Stripe Dashboard (Settings → Installed apps) has the same effect on our side within seconds. Account deletion removes everything, including the Stripe customer record we hold for your own FlowMRR subscription.
Two paths, one outcome: connect with Stripe for the simplest setup and automatic real-time updates, or paste a restricted key when you want to decide permission by permission. Either way, the only write FlowMRR ever performs on your account is a payment retry you explicitly asked for.
Can FlowMRR charge my customers or change my prices?+
No. The only mutating call we make is Invoice.pay on an invoice that already exists and has already failed, and only when you click 'Retry payment'. We never create charges, subscriptions, prices or customers, and we never delete anything on your account.
Where are my credentials stored?+
Encrypted at rest (Fernet / AES-128-CBC) in our EU-hosted database. They are decrypted only in memory, for the duration of a sync or a request you triggered. Removing your credentials in Settings wipes them immediately.
Does the read_write scope give FlowMRR access to my Stripe balance or payouts?+
We read your balance to show cash on hand in the Treasury view; we never move money, request payouts or touch bank details. Payout initiation isn't something FlowMRR calls, regardless of the scope Stripe grants.
