Read-only Stripe keys: scopes, verification, and rotation
The right integration is narrow, read-only, and revocable. A key prefix is not a permission model — verify the actual reads you need.
A billing audit needs to read customers, subscriptions, invoices, products, and prices. It does not need to create charges, modify subscriptions, or issue refunds. Use a restricted key with the smallest set of read permissions that supports those queries.
What to request
- Customers: read.
- Subscriptions: read.
- Invoices: read, if invoice state is part of the policy.
- Products and prices: read, to resolve plan names and amounts.
- No write permissions on any resource.
Verify the permission boundary
When a key is saved, make a small read request against each required resource. A successful read verifies that the key can access the data. It does not prove that write permissions are absent; Stripe’s restricted-key UI is the source of truth for the configured scopes. Say that plainly in the product.
Store the key encrypted server-side. Never return it to the browser after submission, and never log it. A prefix check is only an input sanity check.
Plan rotation and revocation
Provide a replace-key flow that overwrites the encrypted secret and records the time. Keep historical snapshots: disconnecting a source should stop future reads, not erase the evidence that previous findings were based on.
If a key is exposed, revoke it in Stripe first, then replace it in the product. Rotating the application’s encryption key is a separate operation and must not be done blindly; existing ciphertext depends on it.
Use test mode for integration work
Stripe test mode is where connection flows, webhooks, and edge cases should be exercised. Live mode should remain disabled until the business, billing, and legal gates are genuinely satisfied. A test-mode success is not evidence that live payments will work.
Primary references