Document restricted API key permissions and setup

[wjrosa]

Towards STRIPE-3
Towards #634

Changes proposed in this Pull Request:

Adds docs/stripe-restricted-api-keys.md: the restricted API key permission list and setup guide that #634 has been asking for since 2018.

The permission list is source-derived: every row traces to a call site in the plugin, split into a tier required by any store, a per-feature tier, and a droppable legacy row (Sources). It also corrects overshooting advice circulating in the issue thread (Radar, Payouts, and blanket Connect permissions are not needed), and documents the two failure modes that generate support volume:

• GET /v1/account has no obvious row in Stripe's permission picker. The doc states plainly that the mapping is unconfirmed, why it fails dangerously (payment methods silently disappear when capabilities is missing), and how to test it. Confirming the row with Stripe is the remaining open item before we can call the list authoritative.
• A missing read permission presents as "your API keys are no longer valid" because the plugin treats any 401 as an invalid key, with a two-hour read blackout after five failures. The doc points merchants at the Stripe request log, where the 403 body names the exact permission.

Depends on:

• Support defining Stripe secret keys as wp-config.php constants #5872 (the WC_STRIPE_SECRET_KEY / WC_STRIPE_TEST_SECRET_KEY constants the setup section recommends)
• Clear the invalid-key error counter when account keys are saved #5873 (the doc's claim that re-saving keys clears the two-hour block)
• Clear OAuth connection metadata when a secret key is replaced #5874 (the decommission section's claim that a manual key save supersedes the Stripe App connection and stops its scheduled refresh)

Should not merge before those three, or the corresponding statements need softening.

Deliberately out of scope: a complete purge procedure for previously stored credentials beyond the "Decommission the standard key" section. That belongs with the key lifecycle work tracked elsewhere and needs a decision on what we want to publish; the doc says a fuller cleanup guide is planned separately.

Testing instructions

Documentation only; render the Markdown and check the links. The permission list itself is best validated by following the doc's "Confirm it for your store" section against a sandbox store.

---

• Covered with tests (or have a good reason not to test in description ☝️)
• Tested on mobile (or does not apply)

Changelog entry

• This Pull Request does not require a changelog entry. (Comment required below)

Changelog Entry Comment

Comment

Repository documentation only; no runtime behavior changes.

Post merge

• Added testing instructions to the Release Testing Instructions wiki page (or does not apply)
• Added the needs docs label (or does not apply)
• Included this PR in the Release Thread scope (or does not apply)

🤖 Generated with Claude Code

https://claude.ai/code/session_0188k5qSpzHE2BagJTfcphKW

[claude]

AI Code Review - Found 1 potential issue

This is a documentation-only PR adding docs/stripe-restricted-api-keys.md. I verified the concrete technical claims against the source. The 401 handling described at the end of the doc is accurate: WC_Stripe_API::retrieve() treats a 401 as an invalid key, counts consecutive 401s against INVALID_API_KEY_ERROR_COUNT_THRESHOLD (5) and stops read requests for INVALID_API_KEY_ERROR_COUNT_CACHE_TIMEOUT (2 hours), clearing the account cache. One accuracy concern below on the wp-config constants mechanism, which I could not find in the current source.

---

_{Automatic review · claude-opus-4-8 · Workflow run}

_{How to reply to a finding}

Reply on this review (or inline at the line the finding refers to) with one of:

• @claude addressed - I made the change. Bot verifies against the next diff before marking resolved.
• @claude rejected: <reason> - Will not fix; reason gets quoted on the next review.
• @claude not-applicable - Finding does not apply (wrong file, already covered elsewhere, etc.).

The bot honours these on the next review pass.

[claude]

AI Code Review [fix here]

Issue: The "Option 1" constants mechanism doesn't appear to exist in the current codebase, yet it's presented as the recommended way to install the key. A grep for WC_STRIPE_SECRET_KEY / WC_STRIPE_TEST_SECRET_KEY finds no reads anywhere in includes/. The actual key-read path is WC_Stripe::get_settings() -> get_option( 'woocommerce_stripe_settings' ) (includes/class-wc-stripe.php:26) and WC_Stripe_API::set_secret_key_for_mode() (includes/class-wc-stripe-api.php:103), both of which read only the DB option with no constant override. The plugin is currently at WC_STRIPE_VERSION 10.9.0, but the doc attributes the feature to 11.0.0. A store owner on 10.9.0 who follows this "recommended" step would define constants that do nothing while believing their key is protected from DB leaks.

Suggestion: Confirm the constants feature actually lands before (or with) this doc. If it's genuinely part of an upcoming 11.0.0, either land this doc alongside that feature PR, or add an explicit "requires 11.0.0+ (not yet released as of this writing)" caveat and demote Option 1 from "recommended" until the code exists. If the constant names or option-write-skip behavior differ from what ships, update them to match.