Best practices for managing secret API keys

Secret API keys are a form of account credentials, like a username and password. In contrast to publishable keys, which are safe to include in webpages and apps, you must limit secret API keys to your server environment and protect them from exposure. If a bad actor obtains your secret key, they can use it to harm your business and other parties in the Stripe ecosystem.

You must keep your secret API keys safe. Follow these best practices, including using Stripe-offered security features.

Protect against compromised secret API keys

Take the following actions to prevent key leaks and secure your keys in place:

• Use secure key management systems (KMS) to store secret keys: When you create a live secret key from the Stripe Dashboard, you’ll see it only one time. Immediately copy the key to a KMS, which handles sensitive information with encryption and access controls. Make sure you don’t leave a copy of the key in your application’s source code or other local files.
• Grant access only to those who need it: Define a clear policy about which users have permission to create, update, or read keys. Limit access only to those who need it. Audit key permissions and access logs periodically to avoid excess privilege on keys.
• Don’t share secret keys insecurely: Don’t share keys in emails, chat messages, or customer support messages. Stripe will never ask you for your secret API key.
• Don’t store keys in source code repositories (such as GitHub): Fraudulent actors scan public source code repositories for API keys, so never commit your secret key. Even if your source code repository is private, copies of the code might be in team members’ development environments, where a compromised application could read them.
• Don’t embed secret keys in applications: Fraudulent actors can exploit secret keys by matching a certain string pattern in the application. Don’t embed secret keys in applications such as client tools, SDKs, and mobile apps. Instead, embed publishable keys, which are intended for those use cases.
• Rotate your API keys periodically: Define and exercise a process for rotating your Stripe API keys. This helps you understand where your keys are used and prepares your organization in the event your API key is compromised. With a routine key-rotation process in place, you can respond to a compromised API key event with a minimum of impact on your business.
• Audit API request logs to monitor suspicious activities: Regularly audit or monitor API request logs to proactively identify misused API keys. Make sure your developers aren’t using live keys when a Sandbox key is appropriate. Learn more at Sandbox versus live mode.
• Keep your training and documentation up to date: Maintain up-to-date documentation about how to handle secret API keys within your organization. Host regular training sessions to reinforce best practices.

Customize API access with restricted API keys

You can create restricted API keys to grant limited access to the Stripe API. Sharing restricted keys is safer than sharing your secret key.

With restricted keys, you can limit the potential impact of a compromise. For example, if you want to give a Stripe API key to a third party that monitors disputes, you can create a restricted key that grants read-only access to dispute-related resources in your Stripe account and blocks everything else. If the third party were compromised, a bad actor who stole your key would be limited to just those API calls.

Limit the IP addresses that can send API requests

You can increase the security of a secret or restricted key by limiting the IP addresses that can use it to send API requests. We recommended this if your service has stable egress IP ranges and a change management process for updating the allowlist when those egress ranges change.

For instructions about how to restrict a key to one or more IP addresses, see how to limit secret or restricted keys to a list or range of IP addresses.

Handle compromised secret API keys

If you identify a compromised secret API key, such as an accidental publication to GitHub, immediately rotate the key in the Stripe Dashboard and replace the old key in your integration. If you detect abnormal behaviors without confirming that the API key is compromised, we recommended that you rotate the API keys proactively while investigating the root cause in parallel.

If Stripe detects an exposed secret API key, we notify you immediately and request that you rotate the key. You must act promptly to reduce potential damages and financial losses caused by unauthorized use of the compromised key until you deactivate it. In some cases, we might deactivate the key proactively. In this case, we notify you about any actions we take.

Stripe doesn’t guarantee that we detect all compromised keys. You’re responsible for following these best practices to prevent compromised keys and making sure your integration with Stripe is secure.