How to Create Restricted Stripe API Keys for Migrations
Last updated:
When migrating Stripe subscriptions, security should be a top priority. This guide explains how to create restricted API keys with only the permissions needed for migration — nothing more.
Why Use Restricted Keys?
Stripe provides two types of API keys:
- Secret keys: Full access to your entire account
- Restricted keys: Limited to specific permissions you define
For any migration, you should always use restricted keys because:
- Least privilege: Only grant the access needed for the specific task
- Auditability: Restricted keys can have descriptive names
- Risk mitigation: If a key is compromised, the blast radius is limited
- Buyer trust: Demonstrating security best practices during due diligence
Required Permissions for Source Account
The source account (seller’s account) needs read-only access. Here are the minimum permissions:
| Resource | Permission Level | Purpose |
|---|---|---|
| Customers | Read | Read customer data for mapping |
| Subscriptions | Read | Read subscription details for recreation |
| Prices | Read | Read pricing data for validation |
| Products | Read | Read product metadata |
No write permissions are needed on the source account until you’re ready to cancel old subscriptions.
For Canceling Old Subscriptions
If MoveMRR will cancel old subscriptions (recommended), add:
| Resource | Permission Level | Purpose |
|---|---|---|
| Subscriptions | Write | Cancel old subscriptions |
Required Permissions for Destination Account
The destination account (buyer’s account) needs write access to create subscriptions:
| Resource | Permission Level | Purpose |
|---|---|---|
| Customers | Read | Verify customer mapping |
| Subscriptions | Write | Create new subscriptions |
| Prices | Read | Validate price IDs |
| Products | Read | Validate product references |
Step-by-Step: Creating a Restricted Key
In Stripe Dashboard
- Go to Developers → API keys
- Click Create restricted key
- Give it a descriptive name (e.g., “MoveMRR Migration - Read Only”)
- Set permissions for each resource type
- Click Create key
- Copy and securely store the key
Permissions Table (Source Account - Read Only)
For the source account, configure:
- Customers: Read
- Subscriptions: Read
- All other resources: None
Permissions Table (Destination Account - Write)
For the destination account, configure:
- Customers: Read
- Subscriptions: Write
- Prices: Read
- All other resources: None
Key Naming Conventions
Use clear, descriptive names for your restricted keys:
MoveMRR Source - Read Only (Jan 2025)MoveMRR Destination - Migration (Jan 2025)
Include the date so you can identify and revoke keys after migration.
Revoking Keys After Migration
Once migration is complete:
- Go to Developers → API keys
- Find the restricted keys used for migration
- Click the three-dot menu → Delete
Never leave migration keys active longer than necessary.
MoveMRR’s Permission Validation
When you enter API keys in MoveMRR:
- Validates permissions: MoveMRR tests each required permission before proceeding
- Shows missing permissions: If a key lacks required access, MoveMRR tells you exactly what’s missing
- Rejects overpermissioned keys: MoveMRR warns if a key has more permissions than needed
This ensures you’re using least-privilege keys correctly.
Common Permission Errors
”Key does not have permission to read subscriptions”
The restricted key is missing subscription read permission. Edit the key in Stripe Dashboard to add it.
”Key does not have permission to write subscriptions”
The destination account key needs subscription write permission to create new subscriptions.
”Key has more permissions than required”
While not blocking, MoveMRR warns you when a key has unnecessary permissions. Consider creating a more restricted key.
Security Best Practices Summary
- Never use secret keys for migration
- Create purpose-specific keys with descriptive names
- Use minimum required permissions for each account
- Revoke keys immediately after migration completes
- Never share keys via unencrypted channels