Migrate a plugin to Stripe Apps or Stripe Connect
Learn about your migration options and decide how to migrate your plugin.
Use this guide to migrate your third-party integration that requires Stripe users to authenticate with their secret API key (also known as a plugin) to Stripe Apps or Stripe Connect.
Previously, Stripe allowed plugins to request the standard API keys of a user to integrate with their products. Starting 30 September 2024, all plugin developers must use secure authentication methods (OAuth 2.0, restricted API keys, Stripe Connect) to protect users against fraud. All new and existing plugin developers must switch to one of these secure authorisation methods supported by Stripe.
If your integration already uses Stripe Apps or Stripe Connect, this doesn’t apply to you or your users.
Choose your migration path![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Stripe offers multiple solutions for developers migrating plugins. Explore each solution:
Integration type | Suitable for | Designed for |
---|---|---|
Stripe Connect | Best for integrations that are centralised platforms or marketplaces | Designed for integrations onboarding new merchants, embedding payments, and managing money movement |
Stripe Apps | Best for integrations that want to integrate Stripe in third-party tools and services | Designed for adding enhanced functionality for existing Stripe merchants |
Manual setup of restricted API keys and webhooks | Only available if your integration requires custom functionality that isn’t supported by Stripe Connect or Stripe Apps | Designed for users who each must manually create restricted API keys and webhooks |
Pre-migration decision checklist![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Review the following checklist to help you decide on the best migration path for your integration and users:
Onboarding new users who might not have existing Stripe accounts often requires creating a Stripe account for the first time just to use your service. If yes, consider Stripe Connect, as the onboarding flow allows users to create Stripe accounts directly during onboarding.
If you make your integration available for other platforms, consider Stripe Apps. You can install Stripe Apps on most Stripe accounts, regardless of their connection to other platforms. This allows you to make your integration available to a larger base.
If you have a centralised service where your users have their own accounts, consider Stripe Connect or Stripe Apps, and use platform or OAuth 2.0 authentication. Using Stripe Connect or Stripe Apps ensures that your users don’t need to copy and paste API keys, which significantly enhances overall security and streamlines user onboarding.
If customers self-host your integration, Stripe Apps using the restricted API key authentication method is likely to be the best fit. It doesn’t require you to store your secret key on untrusted servers, which is required for Stripe Connect or Stripe Apps with platform authentication.
OAuth 2.0 is an option but requires significant additional work, including hosting a central back-end server where your users create accounts, store the URLs of their self-hosted back ends, and proxy OAuth tokens to those back ends.
If you receive webhook events on your own endpoints, consider Stripe Connect or Stripe Apps, using the platform or OAuth 2.0 authentication methods to set up a central webhook configuration. Doing so allows you to receive webhook events for all of your connected account users.
If users receive webhook endpoints at their own unique endpoints, instruct them on how to configure these endpoints manually, which is common with self-hosted back ends. If you have a special use case that requires managing custom webhook endpoints for your users through the
webhook_
API permission, contact stripe-apps@stripe.com.write Using the connected accounts of other platforms is uncommon – but in some cases, plugins are designed to use the transitive access of a platform’s secret API key to make API calls on behalf of the platform’s connected accounts. Currently, the only supported option is to have your users manually create restricted API keys. When creating the key, the user must tick the appropriate boxes to grant permissions on their connected accounts.
Migrating to Stripe Connect![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Stripe Connect is a solution for centralised platforms. To use Connect, you need to host a web service to securely store your API key and manage connected accounts.
Using your platform API key requires that all API requests to Stripe originate from your servers, use your API key for authentication, and use the Stripe-Account
header to indicate the connected account you’re acting on behalf of. Instead of OAuth 2.0, use the /v1/accounts
API](/connect/oauth-standard-accounts) to securely retrieve access tokens for each connected account. Your servers or your customers’ servers can then make API requests to Stripe using those tokens.
Stripe businesses can only be connected to one Connect platform at a time. Connect allows you to onboard new businesses directly to your platform, but businesses with existing Stripe accounts who want to use your platform need to create new accounts, which might cause extra work your users.
To learn more about migrating from a plugin to Connect, see Build a multi-party integration with Connect.
Migrating to Stripe Apps![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Stripe Apps is a platform for developers to create integrations that extend or enhance Stripe’s functionality for businesses and their users. These integrations can directly customise Stripe’s behaviours or connect third-party tools and services to Stripe.
Stripe Apps also offers an authorisation framework for securely accessing Stripe on behalf of businesses. Additionally, Stripe Apps includes features such as UI extensions, which can improve the functionality and value of your plugin.
Stripe Apps offers three authentication methods to fit different use cases:
- Platform: Designed for Stripe-native integrations that operate as a centralised service, such as a SaaS platform. API requests require the developer’s API key and the Stripe Account header.
- OAuth 2.0: Uses the industry-standard OAuth 2.0 protocol for service-to-service user authentication. This method is ideal for integrations already using OAuth (previously known as Connect Extensions), and provides added benefits such as enhanced management, increased visibility, analytics, and so on through the Stripe Apps platform.
- Restricted API keys (RAK): Automatically generates restricted API keys for each app a user installs. Each app gets a unique API key with only the permissions it needs. Users must still manually copy and paste this key into your integration. While this method boosts security, it adds extra steps for user onboarding.
Compare authentication types for Stripe Apps![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
Before you migrate your plugin to Stripe Apps, compare the three authentication methods:
Authentication | Benefits | Tradeoffs |
---|---|---|
Platform default |
|
|
OAuth 2.0 recommended |
|
|
RAK |
|
|
We recommend platform or OAuth 2.0 authentication because they offer better security and a streamlined onboarding process for your users.
For step-by-step instructions on migrating plugins to Stripe Apps, see:
Migrating to manual setup of restricted API keys and webhooks![](https://b.stripecdn.com/docs-statics-srv/assets/fcc3a1c24df6fcffface6110ca4963de.svg)
If neither Stripe Connect nor Stripe Apps meets your needs, users can manually set up their integration with your service.
To migrate and comply with Stripe’s security requirements, you must:
- Document the setup: Provide instructions for businesses to configure a restricted API key that only has the needed permissions.
- Validate API Keys: Make sure businesses give you restricted API keys that start with the prefix with
rk_
, notsk_
. - (Optional) Document the webhook setup: Guide businesses on setting up webhook endpoints to send data to the correct address.
Note
This authentication method introduces manual onboarding steps for businesses and lacks the benefits of Stripe Connect and Stripe Apps.