Best practices for managing secret API keys

Secret API keys are a form of account credentials, like a username and password. Unlike publishable keys, which are safe to include in webpages and apps, secret keys must stay in your server environment. If an unauthorized party obtains your secret API key, they can make unauthorized charges, access customer data, or disrupt your integration.

Protect secret API keys

You must handle and store your secret API keys safely at every phase of development to protect them from exposure or compromise.

• Never put secret API keys in source code: Bad actors continuously scan public repositories for Stripe API keys. Even private repositories can be exposed through development environments.
  • Use your platform’s secrets management tools (such as a secrets vault) or environment variables to supply API keys to your integration code.
  • Periodically audit your source code, configuration files, and CI/CD pipelines for sensitive keys by searching for sk_live_ and rk_live_. If you find a sensitive key, assume it has been exposed and compromised.
  • Use a pre-commit hook in your version control system to reject commits that contain strings matching these patterns.
  • Code snippets in Stripe’s documentation sometimes include keys for illustration purposes only. Don’t include real keys in your code.
• Never embed secret API keys in applications: Unauthorized parties can unpack applications to search for embedded keys. For client-side use cases such as client tools, SDKs, and mobile apps, embed publishable keys instead.
• Follow the principle of least privilege: People and systems must have only the privileges required to perform their jobs.
  • Define a clear policy about which team members have permission to create, update, or read secret API keys. Limit access to those who need it and audit key permissions periodically.
  • Maintain up-to-date documentation about how to handle secret API keys within your organization. Host regular training sessions to reinforce best practices.
• Handle secret API keys carefully: When you create a secret API key in the Stripe Dashboard, you see it one time. Immediately store the key in your platform’s secret-management tool or an environment variable, and don’t store it anywhere else.
  • Share secret API keys through your platform’s secret-management tools—not in emails, chat messages, or customer support messages. Stripe never asks you for your secret API key.
  • Use restricted API keys with limited permissions instead of unrestricted secret API keys.
• Rotate secret API keys periodically: Define and practice a process for rotating your Stripe API keys. Periodic rotation confirms that you know where each key is used and that your team can replace a key on short notice. Write down a contingency plan so that if a key is exposed or compromised, your team can respond with minimum 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. See Sandbox versus live mode.

Customize API access with restricted API keys

Instead of using secret API keys with broad access, you can create restricted API keys to assign specific privileges to people and systems. For example, you can give your invoicing system the ability to manage invoices and nothing else.

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

Limit the IP addresses that can send API requests

If your service sends API requests from stable IP addresses, you can restrict your secret or restricted API keys to those addresses. For example, if your platform offers a dedicated NAT gateway or another way to reserve an IP address or range, you can configure Stripe to block API requests with your keys from anywhere else.

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

Handle compromised secret API keys

If a secret API key is exposed or compromised, rotate it immediately—even if you aren’t sure anyone saw it. Treat any exposure as a potential compromise.

• Exposure means the key became visible somewhere it shouldn’t have been, such as a public repository, a log file, or an email.
• Compromise means there’s evidence of unauthorized use of the key.

Respond to a key exposure or compromise

Follow these steps when you discover that a secret API key has been exposed or compromised:

1. Rotate the affected key immediately. Rotate the key in the Stripe Dashboard and replace it in your integration. If you set a delayed expiration on the old key to avoid downtime, keep the window as short as possible.
2. Determine which keys to rotate. At a minimum, rotate the specific key that was exposed. If the scope of the exposure is unclear—for example, if a server or credential store was compromised—rotate all secret and restricted API keys on your account.
3. Review your API request logs. Check the API request logs for the affected key. Look for requests you don’t recognize, unexpected IP addresses, or unusual patterns such as spikes in volume or calls to Stripe APIs your integration doesn’t normally use.
4. Contact Stripe support if you see unrecognized activity. If your request logs show activity you can’t account for, contact Stripe support for help investigating and mitigating the impact.

Stripe’s proactive key protection

If Stripe detects an exposed secret or restricted API key, we notify you and request that you rotate the key. In some cases, Stripe deactivates the key proactively and notifies you about any actions we take.

Stripe doesn’t guarantee detection of all exposed or compromised keys. Following these best practices helps you prevent key exposure and keep your integration with Stripe secure.