Best practices for managing secret API keys

Secret API keys are a form of account credentials, like a username and password. If bad actors obtain a secret key, they can use it to harm your business and other parties in the Stripe ecosystem.

Stripe users own the responsibility of keeping secret API keys safe. Here are some best practices for how to do that, including by using Stripe-offered security features.

Protect against key leakage

Take the following actions to protect against leaked secret keys:

• Use secure key management systems (KMS) to store secret keys: When you create a secret live mode key from the Stripe Dashboard, you’ll only see it 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 the local file.
• Grant access only to those who need it: Define a clear policy about which users have permission to create, update, or read keys. Limit the access only to those who need it. Audit the access 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 never asks you for your secret API key.
• Don’t store keys in source code repositories (such as GitHub): Fraudulent actors might scan public source repositories for leaked keys. Even if the source repository is private, it could be shared with team members on their development environments.
• Don’t embed secret keys in applications: Fraudulent actors can exploit secret keys by matching a certain string pattern in the application. Avoid embedding keys in applications such as client tools, SDKs, and mobile apps.
• Exercise your ability to roll your API Keys: Defining and exercising a process for rolling keys helps you understand where your keys are being used and prepares your organization in the event your API key is leaked. By having key rolling processes in place, you can respond to a key leak event with a minimum of impact on your business.
• Audit API request logs to monitor suspicious activities. We recommend that you regularly audit or monitor API request logs to proactively identify misused API keys. Make sure your developers aren’t using live mode keys when a sandbox key is appropriate. Learn more at sandbox versus live mode.
• Regular training and updating documentation. Maintain up-to-date documentation about how to handle secret API keys within your organization and host regular training sessions to make sure best practices are followed.

Customize API access with restricted API keys

You can use restricted API keys to provide limited access to specific API resources. With restricted keys, especially when giving access to third parties, you can allow only the minimum access to required resources and limit the risk of keys. When using microservices that interact with the API on your behalf, define restricted keys that allow only the minimum access those microservices require. For example, if you use a dispute monitoring service, create a restricted key that only provides read access to dispute-related resources. That key allows the service to get the data it needs, but doesn’t allow it to make any changes or access any other data.

Restricted keys can’t interact with many parts of Stripe’s API because their only purpose is to reduce risk when using or building microservices. Don’t use restricted keys as an alternative to your account’s secret or publishable API keys during development of your Stripe integration.

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 leaked secret API keys

If you identify a secret key leak, such as accidentally publishing it to GitHub, immediately roll the key from Stripe Dashboard and replace your integration with the new key. If you detect abnormal behaviors without confirming that the API key is leaked, we recommended that you roll the API keys proactively while investigating the root cause in parallel.

If Stripe detects that a live mode secret API key has been exposed, we notify you immediately and request that you roll the key. You must act promptly to reduce potential damages and financial losses caused by unauthorized use of the leaked key. Depending on the imposed risk and activity on the account, we might decide to roll the key on your behalf. In this case, we notify you about any actions we take.

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