Restricted Stripe API Keys: Scopes & Setup (2026)
Last updated:
Direct answer: A restricted Stripe API key is a secret key limited to the exact resources and permission levels you select — each resource (Customers, Subscriptions, Prices, …) is granted None, Read, or Write individually. You create one in the Dashboard under Developers → API keys → Create restricted key, and it behaves like a normal secret key everywhere the granted permissions suffice. Any tool that only needs part of your account should get a restricted key, never the full secret key.
For migration work specifically: use separate, purpose-specific restricted keys for the source and destination Stripe accounts. Grant only the resources required by the selected migration features, validate the keys before a live run, store live keys in a secrets vault, and revoke them after the observation window.
Do not paste a broad live secret key into migration software when a restricted key can perform the same scoped work.
Primary source: Stripe API-key security best practices.
Why the Two Keys Need Different Permissions
The source and destination perform different jobs:
- the source is read for Customers, subscriptions, catalog, and mappings, then may need Subscription write access for the selected deactivation strategy;
- the destination is read and written because the migration creates or maps Customers, Products, Prices, Coupons, and subscriptions;
- webhook permissions are only needed when webhook-endpoint migration is enabled.
A read-only source key is not sufficient when MoveMRR is expected to cancel, pause, or mark source subscriptions to end. Conversely, granting write access to every Stripe resource would exceed the migration’s needs.
MoveMRR’s Current Permission Profiles
MoveMRR generates Stripe’s restricted-key creation URL with these base permissions preselected:
| Resource | Source key | Destination key |
|---|---|---|
| Customers | Read | Read and write |
| Subscriptions | Read and write | Read and write |
| Products | Read | Read and write |
| Prices | Read | Read and write |
| Coupons | Read | Read and write |
| Payment methods | No base permission | Read |
| Webhook endpoints | Read only when enabled | Read and write only when enabled |
The profile can evolve with product capability. Use the permission list displayed inside the current MoveMRR project rather than copying an old checklist.
Create and Validate Each Key
- Open the Connect stage for the migration project.
- Choose source or destination.
- Review whether webhook-endpoint migration is enabled.
- Open the generated Stripe restricted-key link.
- Verify the preselected permissions in Stripe.
- Create a clearly named key for that account and project.
- Return it through MoveMRR’s secure key form.
- Confirm the reported account ID, live/test mode, and permission validation.
- Repeat for the other account.
Never send a live key through email, a ticket, chat, or a shared document.
How MoveMRR Stores Keys
The previous statement that MoveMRR “does not persist API keys” was inaccurate. MoveMRR stores project keys so that scheduled, rehearsed, and live work can use them.
Current behaviour:
- stored live keys use Supabase Vault;
- live keys are not silently downgraded to insecure fallback storage when Vault is unavailable;
- a stored key is not returned to the browser;
- stored keys expire inside MoveMRR after 30 days, which does not revoke the underlying credential in Stripe;
- rotation replaces the stored credential and resets its expiry;
- the UI reports age, expiry, account, mode, and permission-validation status.
This does not remove the account owner’s responsibility to restrict, monitor, rotate, and revoke the key in Stripe.
Key Lifecycle
| Stage | Action |
|---|---|
| Preparation | Create one key per side and per purpose |
| Rehearsal | Confirm test/live mode and validate required permissions |
| Live cutover | Restrict operator access and monitor Stripe request logs |
| Observation | Keep only the credentials required for agreed verification or follow-up |
| Completion | Revoke migration keys in Stripe and remove them from the project |
| Personnel change or suspected exposure | Rotate immediately and review Stripe activity |
If a key appears in source code, logs, analytics, chat, or a public document, treat it as exposed and rotate it.
Do Not Reuse the Migration Key in the Product
The buyer’s production application needs its own account-specific credential with a separate permission model and lifecycle. Do not turn a temporary MoveMRR migration key into the application’s permanent Stripe key.
After migration:
- create or rotate the buyer application’s production credentials;
- deploy them from a secret manager;
- verify the authenticated destination account;
- replace the client-side publishable key separately;
- deploy new webhook signing secrets;
- revoke source and migration credentials when the cutover owner approves.
See the application handover runbook.
Security Limits
A restricted key reduces impact; it does not make credential handling risk-free. A key with Subscription write access can still change financially important objects.
Maintain:
- two-step authentication for Stripe administrators;
- the smallest operator group possible;
- IP restrictions where compatible with the running environment;
- Stripe request-log review;
- an explicit live-run confirmation;
- an incident owner and key-rotation procedure.
MoveMRR never needs raw card numbers. Eligible payment credentials are copied by Stripe through the account-copy process.