Restricted API keys

RevBridge is designed around scoped Stripe access. Do not share root secret keys for a migration project.

Production projects require restricted API keys with the rk_... prefix. Unrestricted sk_... secret keys are rejected by default because Stripe treats them as full account credentials rather than scoped migration credentials. Live secret keys with the sk_live_... prefix are never accepted.

Restricted API keys reduce blast radius and make the migration easier to review. They also make it clear which account is the seller source and which account is the buyer destination.

Key roles

A project uses two Stripe accounts:

• The seller account is the source for existing customers, subscriptions, prices, coupons, and billing state.
• The buyer account is the destination where buyer-side subscriptions are created.

Use separate keys for each role.

What RevBridge verifies

RevBridge verifies keys before allowing the project to proceed. The app shows the last four characters of each saved key so operators can confirm which credentials are attached.

During key setup, RevBridge performs harmless read-scope checks against the source and destination accounts. It verifies the source key can list subscriptions, customers, prices, products, coupons, invoices, invoice items, tax IDs, PaymentIntents, Charges, and card PaymentMethods, and that the destination key can list customers, subscriptions, prices, products, coupons, invoices, invoice items, tax IDs, and card PaymentMethods. If one of those checks fails, setup returns a specific error naming the missing operation.

Write-scope checks happen later at execution time because they require a safe no-op update or temporary object write. Before buyer-side subscription creation, RevBridge verifies source subscription update scope by preserving the current cancel_at_period_end value on the first planned source subscription. It also verifies destination write scope by creating and deleting an inactive temporary product.

If verification fails, the project should remain blocked until the key scope or account selection is corrected.

For controlled local development only, operators can set ALLOW_STRIPE_SECRET_KEYS=true to permit sk_test_... keys while creating restricted keys. Do not enable that override in production.

One-click key creation

The project console's Restricted keys card has Generate source key and Generate destination key buttons. Each opens Stripe's create-restricted-key page with every required permission pre-selected and the key pre-named (RevBridge Source / RevBridge Destination), so there is nothing to hand-pick: sign in to the seller account for the source key and the buyer account for the destination key, review the pre-selected rows, and click Create key. Test-mode variants of both links are provided for sandbox runs.

Always confirm the Stripe account shown in the dashboard header before creating the key — the link opens whichever account you are signed in to. If a permission row shows None after the page loads (Stripe occasionally renames permission identifiers), select it manually using the guidance below; RevBridge's key verification will name anything that is missing.

Permission guidance

Create separate restricted keys for the seller/source account and buyer/destination account. The exact labels in Stripe's dashboard can change, but the resource areas should map to these capabilities.

No account-information row is needed on either key. RevBridge verifies the two keys belong to different accounts in the same mode using an account lookup when the key carries the optional "Basic Business Contact Information Read" permission, and otherwise by comparing the account identity Stripe embeds in every modern key — so keys created through the generate buttons work as-is. Do not select Stripe's KYC resources group when creating a key: the dashboard cannot combine it with normal resource rows, and RevBridge never reads KYC data. (Adding it later via the key's edit page is allowed and harmless, but unnecessary.)

Source key:

• Customers read, including legacy sources/cards.
• Payment methods read.
• Subscriptions read and write. Write is required only to verify update scope and set cancel_at_period_end=true after a destination subscription is confirmed.
• Prices and products read.
• Coupons read.
• Invoices read.
• Invoice items read, so RevBridge can block pending invoice items that would otherwise alter the next invoice.
• Tax IDs read, so RevBridge can block customer tax IDs through Stripe's dedicated Tax IDs API.
• PaymentIntents and Charges read, so RevBridge can resolve the latest paid card when no subscription or customer default exists.

Destination key:

• Customers read and write. Write is used only for safe invoice_settings.default_payment_method updates.
• Payment methods read and legacy sources/cards read.
• Subscriptions read and write.
• Products and prices read/write.
• Coupons read/write.
• Invoices read, so RevBridge can inspect the newly created subscription's initial invoice before scheduling source cancellation.
• Invoice items read, so RevBridge can block buyer-side pending invoice items that would otherwise alter migrated invoices.
• Tax IDs read, so RevBridge can block buyer-side customer tax IDs through Stripe's dedicated Tax IDs API.