Your Stripe key
One Stripe restricted key per site — the permissions to tick, why each is needed, what to do when a fix needs one more, and how an agent stores the test-mode key itself.
Checkbox needs one Stripe restricted key per site. The same key reads your settings for the checks, makes the one-click fixes (only after you click Approve on each one) and, in test mode, runs test subscriptions. You never create a second key for a fix.
Connect with Stripe. On app.checkbox.site you can connect Stripe without a key: Settings › Billing connection → Connect with Stripe installs the read-only Checkbox Stripe App, and Checkbox reads your prices, Checkout settings, customer portal and subscription events through it. A test-mode restricted key is then only for test runs, with fewer permissions (Customers: Write, Products: Read, Prices: Read, Subscriptions: Write, Test clocks: Write, Customer portal: Write, Checkout Sessions: Write, Payment Links: Read), and Checkbox asks for it only when a test run is wanted. Self-hosted servers, and sites that sell on a Payment Link for now, use the one key below.
Create the key
In Stripe open Developers → API keys (dashboard.stripe.com/apikeys; in test mode, dashboard.stripe.com/test/apikeys) → Create restricted key. Name it Checkbox, set every permission to None, then tick the permissions below. The key needs some Write permissions, but Checkbox's checks only read: the list is grouped by what each permission is used for (the same list, in the same words, as the dashboard checklist).
Read — used for checks
| Resource | Access | Why |
|---|---|---|
| Products | Read | Plan names next to your prices. |
| Prices | Read | Amounts, billing intervals and trial lengths, compared with what your pages say. |
| Coupons | Read | Only when your hosted cancellation page offers a coupon as the save offer. Optional. |
Write — used only for a fix you approve, for test runs in test mode, and for Checkbox's own webhook
Each of these also covers the read the checks need (in Stripe, Write includes Read). The last column says when Checkbox actually writes with it.
| Resource | Access | Why | When Checkbox writes |
|---|---|---|---|
| Customers | Write | Hosted cancellation page: finds the subscriber by email (Read). Test runs: create a test customer (Write, test mode only). Optional. | Used only in test mode (test runs). |
| Subscriptions | Write | Read: which trials subscribers actually get. Write: cancels when a subscriber asks on your hosted cancellation page, and test runs create test subscriptions. | Used only after you turn on the hosted cancellation page (you approve it in one click), or in test mode. |
| Test clocks | Write | Test runs fast-forward through trial end and renewal (test-mode keys only; nothing is charged). Optional. | Used only in test mode. |
| Customer portal | Write | Read: whether subscribers can cancel online and your portal link. Write: test runs open the portal to cancel the test subscription; on a live key, only if you want the Go live page button that turns on cancellation in your live customer portal. | Used in test mode (test runs). In live mode only when you click “Turn on cancellation” on the Go live page and confirm the listed change. |
| Checkout Sessions | Write | Read: your checkout text and terms-consent setting. Write: test runs start a test checkout. | Used only in test mode (test runs). |
| Payment Links | Write | Read: consent and renewal text on your Payment Links. Write: the Payment Link fix, only when you click Approve. | Used only after you click Approve on the Payment Link fix, or a Go live page button (create the new live link; later, turn the old one off) and confirm the listed change, or in test mode. |
| Webhook Endpoints | Write | Registers Checkbox's webhook endpoint, so renewals and cancellations are seen as they happen. | Used once, when you connect the key, to add Checkbox's own webhook endpoint (and to remove it when you disconnect); nothing else. |
Checkbox never uses the key to refund, charge or pay out, and never changes a real customer or subscription except the cancellation your subscriber asks for on the hosted cancellation page.
On your live key: the two Go live changes
On the Go live page, Checkbox can make exactly two kinds of change in your live Stripe account, each only when a person signed in to the dashboard clicks its button and confirms the list of Stripe objects and fields it shows first:
- Customer portal: Write: turns on cancellation in your default live customer portal configuration (
features.subscription_cancel: enabled, at the end of the period, no proration; andlogin_page.enabled). - Payment Links: Write (only when your link needs Stripe's terms checkbox: maximum protection): creates the new live Payment Link (same price,
consent_collection.terms_of_service = "required", the checked renewal terms incustom_text), and later, in a separate click once a check has seen the new link on your site, setsactive = falseon the old live link. Otherwise you add the renewal line to your current live link yourself and this permission is not needed.
Both permissions are optional on the live key: without them the buttons say which one to add, and you make the same changes yourself in Stripe. Every live change is recorded with who clicked, when, the Stripe object ids and Stripe's answer before and after. API keys and AI agents can never make these changes.
The dashboard shows the same list as a checklist next to the key field (Site → Settings → Billing). Secret keys (sk_…) are refused: they can do everything in your account. Stripe does not document a link that opens the restricted-key form with these permissions filled in, so Checkbox links to the API keys page.
When a fix needs one more permission
Checks never write. When you approve a fix and the key lacks the permission it needs, Checkbox says which one, for example "The Stripe key is missing Payment Links: Write". Edit the same key in Stripe and set that permission, or paste a replacement key with every permission above in Site → Settings → Billing. The API answers with code: "stripe_permission_missing" and the permission to add.
Keys saved before this change, one per fix, keep working until you delete them; Checkbox then uses the connected key.
Agents store the test key
An agent that set up Checkbox (after the owner approved it through the approval link) stores the site's test-mode restricted key itself, from the project's environment, with createTestCredential (MCP: store_stripe_test_key):
POST /v1/sites/{site}/test_credentials with { "type": "stripe_test", "secret_key": "rk_test_…" } (the Test subscriptions guide has the full request).
- Where: API: createTestCredential (POST /v1/sites/{site}/test_credentials). MCP: store_stripe_test_key, in the local server (@checkbox-site/mcp on npm) from 0.2.1; the hosted server (app.checkbox.site/mcp) may not list it yet, and then the owner adds the key in the dashboard (Site → Settings → Billing).
- Checkbox checks the key with Stripe the way the dashboard's Connect Stripe does. On a test-mode site without a Stripe connection it becomes the site's connection too: one key for checks, fixes and test runs.
- Live keys (
sk_live_…,rk_live_…) are refused (test_key_not_test_mode): a person adds live keys in the dashboard. Secret keys (sk_test_…) are refused (test_key_not_restricted) with the permissions to tick. - Every store is shown to you: the site's setup timeline and the Billing connection line say the agent's name and the time, for example "Test key added by Claude Code at 14:02", with a one-click Revoke key. Revoking removes the key everywhere Checkbox holds it.
- If the owner did not allow the agent to use the project's test key on the approval page, the agent cannot store one (
test_key_declined); the owner adds it in the dashboard.
Agents never ask you to paste a key into a chat. When the project has no restricted test key, the agent asks you to create one with the checklist above and put it in the project's environment file.
Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). You remain solely responsible for your subscription program, and Checkbox takes on no legal liability for it (Terms). Checkbox is a System1 company; Trust center · Status. For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.