A new API key should start with the narrowest useful scope, an expiry date, an owner, and a format that is easy to recognise and revoke. Broad, permanent keys are the default customers drift into because they are convenient. Make the safe choice the easy one in your console and your SDK.
Why defaults matter more than documentation
Most customers create a key once, paste it into a config file and never look again. Whatever your console offers on the first screen becomes the production setting for years. If the default is full access with no expiry, a single leaked key gives an attacker everything, indefinitely.
OWASP's REST Security Cheat Sheet notes that API keys help with abuse and denial of service, but that issued to third party clients they are relatively easy to compromise. It advises not relying exclusively on API keys to protect sensitive, critical or high value resources, requiring them on every request to protected endpoints, returning 429 when requests come too quickly, and revoking a key when a client violates the usage agreement.
A table of defaults
| Property | Safer default | Why |
|---|---|---|
| Scope | Read only, or the smallest set the user picks | Limits damage from a leak |
| Expiry | Finite, with a reminder before it lapses | Stale keys are a long tail of risk |
| Owner | Named user or service, required | Someone must answer for each key |
| Environment | Separate test and production keys | Test keys in code samples do no harm |
| IP or origin restriction | Optional but prominent | Cuts reuse from elsewhere |
| Rate limit | Applied per key | Contains abuse |
| Format | Prefix naming the product and environment | Easy to spot in code and logs |
| Display | Shown once at creation, stored hashed | Support cannot leak what it cannot see |
Steps to implement
- Make scope selection part of key creation, with nothing pre-ticked beyond read access.
- Require an expiry, and offer shorter choices first. Send email and dashboard warnings ahead of expiry.
- Record the creator, the purpose and the last used time, and show them in a key list. A key unused for a long period can be proposed for revocation.
- Store only a hash of the key on the server and show the secret once.
- Use a distinctive prefix that identifies the key type. It makes accidental commits easier to find with any scanner a customer runs, and it helps your support team avoid asking people to paste whole keys.
- Provide one click revoke and rotation with an overlap period, so customers can roll keys without downtime.
- In the SDK, read the key from an environment variable by default and never print it. See SDK logging defaults and keeping keys out of URLs.
- Alert customers on unusual use, such as a key suddenly used from a new network or at a new volume.
Keys are not the whole story
For sensitive operations, prefer short lived tokens issued through an authorization flow over long lived static keys. Keep static keys for simple, low risk integrations. The point is to match the credential to the risk, and to have a way to retire the weaker ones over time.
Documentation to publish
State what each scope allows, how long keys last by default, how to rotate, and what to do if a key leaks. Include the revoke steps, since people read that page in a hurry.
Quick check
Should keys ever be permanent?
Avoid it. If a customer needs a long life, make them choose it deliberately, and keep rotation easy.
Why show the secret only once?
Because you can then store a hash, and a database leak or a support screen cannot reveal working keys.
Safeguard's agent identity, policies and guardrails help control which credentials automated agents and tools can use. You can also run the free scan on a repository.
Sources
Last reviewed: 19 October 2026.
