Stripe API Keys Security Guide: Restricted Keys, Rotation and Leak Response

A Stripe secret API key is a payments credential that can move money, read customer data and change account settings, and it usually lives in more places than anyone has written down. Stripe offers several key types, scoped permissions, network access policies, scheduled rotation and request logs, but none of them help unless an organisation chooses the right key for each workload and knows where every key is used. This guide explains how Stripe authentication works for people and for code, which Dashboard roles can create keys, how to replace unrestricted secret keys with restricted keys, what to log and alert on, and how to respond when a key leaks. It is written for platform, application security and identity teams who run or audit a Stripe integration, and it describes product features from Stripe's own documentation without recommending any vendor.

Key takeaways

• Only the publishable key is safe to expose. Secret (sk_), restricted (rk_) and organisation (sk_org_) keys are server-side secrets, and webhook signing secrets (whsec_) are a separate credential with their own rotation.
• Restricted keys should be the default. Stripe itself no longer recommends secret keys for new use cases; a restricted key per service, with None, Read or Write per resource, caps what a stolen key can do.
• Access policies turn a stolen key into an alert. Binding live keys to known IP ranges, or to an ASN and country with anonymising sources blocked, means a request from anywhere else is refused and reported.
• Rotation is a rehearsed procedure, not an event. The Dashboard gives up to 7 days of overlap; use it to roll out gradually and expire the old key only after its request logs show zero traffic.
• A leaked payments key needs a payments response. Rotate first, then review request logs, connected accounts, external bank accounts, payouts and refunds, because the damage is financial as well as data exposure.

How identity and access work in Stripe

Stripe has two separate access planes. People sign in to the Dashboard with a user account, a role and (ideally) single sign-on. Code authenticates to the API with an API key sent as a bearer credential. The key, not the person who created it, is the identity Stripe sees on each API request, which is why API keys are non-human identities that need owners, scopes and lifecycles. See the Non-Human Identity (NHI) Guide.

Key types

Sandbox and live mode

Sandbox and live mode each have their own keys and objects. Stripe's guidance is to scan for sandbox keys as well as live keys and to check developers are not using live keys where a sandbox key would do. A useful rule: no live key on any developer workstation.

Reveal-once behaviour

In live mode, a secret or restricted key that a user creates is shown once and cannot be revealed again; Stripe cannot recover it. Keys Stripe creates for you (the default secret key, or the replacement produced by a scheduled rotation) can be revealed later from the API keys page. Each key has a Note field that Stripe suggests using to record where the key is stored, the cheapest inventory control available.

Admin roles and privileged access

Whoever can create API keys can mint a credential with full account access, so the Dashboard roles that hold that permission are privileged roles in the PAM sense. Stripe's role documentation lists which roles can create, view, edit and delete API keys.

• Treat the Developer role as privileged: it is the role most often handed out by default, and it can create an unrestricted live secret key. Give engineers Sandbox User or Sandbox Admin for build work and grant Developer in live mode only to the few people who deploy production credentials.
• Watch roles that can invite users: Stripe warns that an attacker who compromises a user with an inviting role can add further users under their control. New team members appearing outside a joiner process are a high-priority alert.
• Use SSO and SCIM: Stripe supports mandatory SAML 2.0 SSO, role assignment through SSO Role IDs, and SCIM provisioning. Without SCIM, Stripe documents that a user removed in the identity provider keeps access until their session expires, so remove leavers in Team settings or enable SCIM. See the SCIM Provisioning Guide.
• Protect key creation with step-up: creating a secret or restricted key asks for a verification code sent by email or text message. Strong Dashboard sign-in (Stripe's compromised-key guidance names passkeys or SSO) matters because this code goes to the signed-in user.

Integrations, API tokens and service accounts

The aim for every key held by a backend service, third-party tool or AI agent: one restricted key per use case, in a vault, bound by an access policy, with a recorded owner.

Choosing the right credential

Migrating from a secret key to restricted keys

1. Inventory usage: search the codebase for Stripe SDK calls and list every third-party integration using the key. Map calls to permissions, for example PaymentIntent.create to Payment Intents: Write and Customer.retrieve to Customers: Read.
2. Read the key's request logs: from the key's menu, View request logs opens Workbench. GET requests map to Read; POST and DELETE map to Write, and Write includes Read.
3. Build and test in a sandbox: create the RAK in a sandbox, start at zero permissions or a narrow preset, run every code path, and add permissions only where the logs show permission errors.
4. Create the live RAK with the tested permissions, load it into the production vault and deploy to a subset of instances first.
5. Retire the secret key: rotate or expire it with a delayed expiry (up to 7 days) as a rollback window, then confirm zero traffic before the window closes.

Storage and handling

• Vault first: Stripe recommends a secrets vault that supplies keys at runtime, audits access and supports rotation; environment variables are the fallback, marked sensitive where the platform supports it. See the Cloud Secrets Managers Guide.
• Never in source or images: no keys in repositories, configuration files, CI definitions or container images, and a pre-commit hook with a scanner that carries maintained Stripe patterns. See the Git Secret Scanning Guide.
• Never over chat or email, or on error pages: Stripe never asks for a secret key, so any request for one is a phishing signal.

Webhook secrets

Webhook endpoints should verify the Stripe-Signature header against the raw request body with the endpoint's whsec_ secret using an official library, and accept requests only from Stripe's published webhook IP addresses. Live endpoints must use HTTPS with TLS 1.2 or 1.3. Roll each endpoint's secret periodically or on suspicion; the Roll secret action can keep the old secret valid for up to 24 hours while receivers are updated. See the Webhook Secrets Security Guide.

Logging and detection

Stripe gives three useful telemetry sources: per-key API request logs in Workbench, the security history audit log for Dashboard activity (visible to Administrator, Super Administrator, IAM Administrator, Developer and some other roles), and webhook events that the integration already receives. Access policy blocks add a fourth, because Stripe notifies the account when a request is refused by a policy.

Stripe notifies you when it detects an exposed key and may deactivate it, but does not guarantee detection: a backstop, not a control.

Responding to a leaked key

Stripe distinguishes exposure (the key was visible somewhere it should not be, such as a repository, a log or an email) from compromise (evidence of unauthorised use), and asks for immediate rotation in both cases. Its support guidance on compromised keys sets out the steps below.

1. Rotate the key from the API keys page, with a short expiry long enough to deploy the replacement; choose Now if there is evidence of abuse.
2. Delete the old key once the new one is confirmed. Deletion is immediate and its logs remain viewable.
3. Review request logs for both keys and Workbench for activity that does not match your integration.
4. Check money movement: pause or reject unfamiliar connected accounts and external bank accounts, reverse unauthorised payouts quickly (reversal is not guaranteed), and refund fraudulent charges to limit disputes.
5. Rotate every other secret and restricted key, because a source that leaked one key often held others.
6. Remove the exposure source (repository history, logs, tickets, paste sites) and rotate again if a further copy turns up; contact Stripe support for help with payout reversals.

Pasting payloads into online tools is a frequent source: the JSONFormatter and CodeBeautify leak exposed payment gateway credentials among more than 80,000 saved pastes. For the generic procedure, see the Secrets Rotation Runbook Template.

Metrics that show it is working

• Restricted key coverage: share of live server-side keys that are RAKs rather than secret keys (target: 100 percent, with documented exceptions).
• Access policy coverage: share of live secret and restricted keys with an access policy attached.
• Key age: oldest live key and median age against your rotation interval.
• Inventory quality: share of keys with a named owner and a Note pointing to a vault location.
• Rotation time: elapsed time from a leak alert to the old key showing zero requests, measured in drills.
• Privileged users: count of users holding Super Administrator, Administrator or Developer in live mode.

Hardening baseline

Phased rollout

1. Weeks 1 to 2, discover: export the API keys list for every account and sandbox, record owner, purpose and storage location in each key's Note, and run a secret scan across repositories, CI logs and images for sk_live_, rk_live_, sk_org_ and whsec_ strings. Treat any live hit as exposed.
2. Weeks 2 to 4, people: enforce SSO, connect SCIM, move engineers to sandbox roles, and reduce Super Administrator, Administrator and Developer in live mode to named individuals.
3. Weeks 3 to 6, access policies: create one policy per environment (for example "Production servers" by NAT gateway CIDR, or an Advanced policy by cloud ASN and country with Tor exit nodes, anonymous VPNs and public proxies blocked). Apply to a low-risk key first, watch for blocked legitimate requests, then extend to all live keys. Roll back by setting the key's policy to None; note that editing a policy changes every key it is attached to at once.
4. Weeks 4 to 10, restricted keys: migrate each service from the secret key to its own RAK using the sandbox-first procedure above, then expire the secret key.
5. Ongoing, rotation and drills: set a rotation interval by key risk, use scheduled rotation where the integration can reload keys, and run a timed leak drill on a sandbox key each quarter.

Small and large organisations

• Small teams: a RAK per service, an access policy, a vault or sensitive environment variable, and two named account owners.
• Larger estates: add restricted organisation keys only for real cross-account work, IdP-driven roles, central log collection, and agent-tagged keys with approval rules for automation that moves money.

Framework mapping

On the threat side, leaked keys in files and repositories correspond to MITRE ATT&CK T1552.001 Credentials In Files, and an attacker adding their own key or user to keep access corresponds to T1098.001 Additional Cloud Credentials. Card data scope is a separate question: see the PCI DSS 4.0 Guide.

Common misconfigurations

• The default secret key in every service: one unrestricted sk_live_ key shared by billing, reporting, support tools and a vendor, so any one compromise grants full account access and rotation breaks everything at once.
• Restricted keys with Write on everything: teams create a RAK, select Write for every category to make errors go away, and never prune. The key is restricted in name only.
• No access policy on live keys: a key copied from a log works from any network, and nobody is told. Deleting a policy also silently reopens every key it covered.
• Live keys outside production: keys on laptops, in CI variables shared with pull request builds, or pasted into online formatters and support tickets.
• Rotation without telemetry: expiring the old key on a timer rather than at zero request volume, causing outages that teach teams to avoid rotating.
• Unverified webhooks: endpoints that parse JSON before checking the signature, or that never roll whsec_ secrets, letting forged events trigger fulfilment or account changes.

Practitioner checklist

• List every live and sandbox key with owner, purpose and vault location recorded in its Note.
• Replace each server-side secret key with a restricted key per service, built from request logs in a sandbox.
• Attach an access policy (IP ranges or ASN and country, with anonymising sources blocked) to every live secret and restricted key.
• Store keys in a secrets vault, mark any environment variable fallback as sensitive, and block keys in commits with a pre-commit scanner.
• Limit Super Administrator, Administrator and Developer in live mode to named people; give engineers sandbox roles.
• Enforce SSO and SCIM so leavers lose Dashboard access immediately.
• Tag any key used by an AI agent for agent access so approval rules cover payouts, refunds and configuration changes.
• Verify webhook signatures on the raw body, allowlist Stripe webhook IPs and roll whsec_ secrets on a schedule.
• Alert on access policy blocks, new keys, new users and role changes, and review key request logs monthly.
• Run a timed leak drill each quarter covering rotation, request log review and payout checks.

Standards and references

• Stripe: API keys
• Stripe: Best practices for managing secret API keys
• Stripe: Restricted API keys
• Stripe: Protecting against compromised API keys
• Stripe: User roles
• Stripe: Manage webhook endpoints
• NIST: SP 800-53 Rev. 5
• MITRE ATT&CK: Credentials In Files

Related NHI Mgmt Group resources: API Key Management Guide · Twilio Credentials Security Guide · SaaS API Token Security Guide · Secrets Management Guide · Agent Identity and Access Guide