In online commerce, security is paramount. As a developer building integrations with Stripe, it’s critical to continuously implement the latest security practices. Earlier this year, Stripe introduced two new authentication methods, restricted API keys (RAK) and OAuth 2.0 to help developers create more secure integrations. This post guides you on how to implement these methods in your Stripe plugins and explains why moving away from traditional unrestricted secret API keys is not just recommended, but necessary.
What is a Stripe plugin?
A Stripe plugin is a component that integrates with the Stripe API to facilitate payment processing, subscription management, and other financial transactions. These plugins are often built to work with third-party platforms, such as CRMs or CMSs, and are consumed by merchants using these platforms.
Plugins typically require API keys to authenticate requests to the Stripe API, allowing the plugin to perform actions such as processing payments, retrieving customer data, and managing subscriptions. API keys are popular because they offer a straightforward way to establish a connection between the plugin and the Stripe API, enabling seamless transactions without requiring extensive setup.
Many plugins require the merchant user to manually copy their Stripe unrestricted secret API key onto the third-party platform to authenticate the plugin with their Stripe account. This introduces significant risk because these secret API keys grant full access to the merchant's Stripe account. If the key is mishandled, exposed, or compromised, it could lead to unauthorized transactions, data breaches, and potentially catastrophic financial losses. This level of access makes unrestricted secret API keys a prime target for attackers, and their widespread use in plugins, without sufficient safeguards, can expose merchants to unnecessary risks.
To mitigate these risks, Stripe introduced restricted API keys (RAK) and OAuth 2.0. These methods offer more granular control over the permissions granted to third parties, significantly enhancing security by moving from a castle and moat security model to a zero trust.
The traditional castle and moat security model, illustrated by full access API key usage, relies on perimeter defense, wherein the moat (the API key) protects the castle (the account). This approach assumes that anyone within the moat is trustworthy; however, if bad actors gain access to the API key, they can navigate the account freely, exposing it to significant vulnerabilities.
In contrast, the zero trust security model, exemplified by RAK and OAuth 2.0, operates on the principle that no user or system should be trusted by default, regardless of their location. Access is granted based on strict identity verification and least privilege permissions, meaning that even if third parties integrate with the system, they are limited to the specific data and actions authorized for them. This paradigm shift not only enhances security by minimizing exposure, but also significantly reduces the risk of unauthorized access, making it essential for developers to adopt RAK and OAuth for safer integrations.
Here are two options for implementing a zero trust model in your Stripe plugins:
-
Restricted API keys (RAK) exemplify this evolution in security. They enforce the principle of least privilege, allowing developers to define specific permissions for their plugins. This means a plugin can only access the data and perform actions that are absolutely necessary. For instance, if your plugin only requires the ability to view customer data, you can create a RAK with read-only access, effectively minimizing the risk of unauthorized actions and data breaches.
-
OAuth 2.0 further enhances this security model by enabling tokenized, one-click authorization. Instead of requiring the sharing of a secret key, merchants can authorize plugins through Stripe’s OAuth interface, which issues a token with precisely the necessary permissions. This not only streamlines the authentication process, but it also empowers merchants to revoke access easily if needed, all without compromising their entire account.
Together, RAK and OAuth provide a robust framework for securing integrations while ensuring that user controls remain paramount.
Updating existing plugins
If you have pre-existing plugins using a full access Stripe API Key, you have several options to update. Here’s a brief overview of the approaches:
1. Turn your plugin into a Stripe App
Converting your plugin into a Stripe App is an excellent way to use Stripe’s built-in tools for secure and seamless integration. Stripe Apps offer a streamlined setup process, enhanced security features, and the ability to display relevant user interfaces directly in the Stripe Dashboard. This option is ideal for developers looking to provide a more integrated experience for merchants.
Stripe App authentication with RAK
Stripe App authentication with OAuth
Check Stripe Documentation for a comprehensive guide on how to migrate your plugin to a Stripe App.
2. Use Stripe Connect
Stripe Connect is designed for platforms that need to facilitate payments between third-party users. By upgrading your plugin to use Stripe Connect, you can take advantage of its secure onboarding process, robust payment features, and automated compliance management. This option is particularly useful for platforms that operate as marketplaces or need to manage multiple accounts under a single integration. Check Stripe Documentation to learn how to migrate your plugin to Stripe Connect.
3. Manual setup of restricted API keys (RAK)
If you prefer to maintain a more hands-on approach, manually setting up restricted API keys (RAK) allows you to define specific permissions for your plugin without converting it into a full Stripe App or using Stripe Connect. This method gives you complete control over the scope of access your plugin has, ensuring that it operates securely within the limits you set. Check Stripe Documentation to learn how to migrate your plugin to a manual RAK.
Each of these options offers a path to modernizing your Stripe plugins, enhancing security, and ensuring compliance with Stripe’s upcoming requirements.
The cost of non-compliance
Starting on October 29, 2024, Stripe will require all merchants using plugins to authenticate via restricted API keys or OAuth 2.0. This mandate is part of Stripe's ongoing efforts to enhance security across its platform. If you haven’t updated your plugins by June 2025, Stripe may begin charging a fee to those merchants who are still using traditional full access API keys.
Summary
Securing your Stripe plugin is essential to protecting merchant accounts from unauthorized access and data breaches. Traditional full access API keys, while common, present significant risks as they grant full access to a merchant’s Stripe account. If mishandled, they can lead to severe security issues.
To combat these vulnerabilities, Stripe introduced restricted API keys (RAK) and OAuth 2.0. These methods offer more secure ways to authenticate third-party integrations. RAKs allow developers to define specific permissions, limiting access to only the necessary data and actions. OAuth 2.0 enhances security further by providing granular access control, tokenized, one-click authorization, giving merchants greater control over their integrations.
Stripe will mandate the use of RAK or OAuth 2.0 for all plugins starting October 29, 2024. Merchants must ensure that their plugins are updated by June 2025 to avoid potential compliance fees and adhere to Stripe’s latest security standards.
By adopting RAK or OAuth 2.0, you significantly reduce the risk of unauthorized access and enhance the security of your integrations. Upgrading your Stripe plugins is not just about compliance, it’s about safeguarding your clients’ data and maintaining the integrity of their financial transactions.
Refer to the documentation for more information on migrating your plugin to Stripe Apps or Stripe Connect.