A restricted API key is a credential you limit to specific permissions, so a leak can only do what you allowed. Integrations should use one for each job, because an unrestricted secret key can do everything the account can do, and a leaked one is a full account compromise.
Definitions
- Secret key: full access to the API. If it leaks, the finder has the same power as your server.
- Restricted key: the same kind of credential, with permissions set per resource, such as read only on one object and no access to others.
- Publishable key: designed to live in front-end code, and unable to perform sensitive actions.
Stripe's documentation uses exactly these three groupings, says to use restricted keys for most use cases, and states that it does not recommend secret keys for new use cases. It also recommends migrating existing secret key usage to restricted keys. The principle carries over to any API that offers scoped keys.
Why one key per integration
If a reporting tool, a refund script and a support plugin all share one key, you cannot tell which one leaked, and you cannot revoke it without breaking all three. Separate keys give you three small problems instead of one large one.
| Integration | Permissions it needs | Permissions it should not have |
|---|---|---|
| Reporting dashboard | Read on charges and customers | Any write access |
| Support plugin | Read customers, create refunds up to a limit | Account settings, payouts |
| Webhook handler | Read the event object it receives | Anything else |
Steps to move an integration to a restricted key
- List what the integration calls. Check its logs or code for the API operations it makes.
- Create a restricted key with exactly those permissions. Name it after the integration and its owner.
- Test it in a sandbox first, using test keys, so a missing permission shows up as an error and not an incident.
- Store the new key in a secrets manager.
- Switch the integration, watch the request logs, and confirm the old key sees no traffic.
- Expire the old secret key.
- Add a note on the key about where it is stored, as the provider prompts you to do.
Related controls
Stripe also offers access policies, which limit where a key can be used from, such as listed IP ranges or countries. They notify you when a blocked request is attempted. Use them where your integration runs from fixed locations.
Keys that go unused can also be a risk. Remove any key whose request volume has been zero for a long time.
Quick check
Is a restricted key safe to put in a mobile app?
No. Only publishable keys are designed to be exposed. A restricted key is still a secret and belongs on a server.
Is a webhook signing secret an API key?
No. It is a separate per-endpoint secret used to verify that webhooks came from the provider.
Safeguard's asset discovery and policy features help you keep track of which systems hold credentials like these. Try the free scan at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
