Issuing API keys to your customers: generate, hash, show once
Short answer: If your SaaS or platform lets customers connect their own systems, you'll be issuing API keys. Generate each key from a cryptographically secure random source, add a short recognisable prefix, and store only a hash of the key, never the key itself. Show the full key to the customer once, at creation, with a clear "copy it now" message. Let them name keys, limit what each can do, see when each was last used, and revoke or replace them without downtime.
Why issuing keys is different from using them
Most guidance on API keys is about keys you hold for other services: keep them out of code, rotate them, react to leaks. Issuing keys to your own customers turns that around. You're now the provider, and a careless design leaves customers' integrations, and their data, exposed.
Small software businesses tend to start with the quickest version: a random string stored in plain text in the users table, shown on a settings page whenever the customer looks. That works until a database backup leaks, a support agent screenshots the settings page, or a customer needs to cut off one integration without breaking the others.
Generating keys
- Use a secure random generator, not the language's general-purpose random function. Python's documentation, for example, points to its
secretsmodule for this and notes that 32 bytes (256 bits) of randomness is believed sufficient for typical uses.secrets.token_urlsafe(32)produces a URL-safe string from that many random bytes. Other languages have equivalents. - Add a prefix that identifies your service and the key type, such as
acme_live_oracme_test_. Prefixes help customers tell keys apart, help support staff recognise a key without seeing it all, and make it easier for secret-scanning tools to spot leaked keys. - Avoid meaning in the random part. Don't encode the customer ID or permissions in the key itself.
Storing keys
Treat keys like passwords:
- Store a hash, not the key. When a request arrives, hash the key it carries and look up the hash. If your database is ever exposed, attackers get hashes they can't use.
- A fast hash is acceptable here, unlike for passwords, because long random keys can't be guessed. A keyed hash (HMAC with a server-side secret) adds protection if the database leaks without your application secrets.
- Keep a short visible part, such as the prefix plus the last four characters, so the customer can recognise each key in the dashboard.
- Compare safely. If you ever compare secrets directly, use a constant-time comparison such as Python's
secrets.compare_digest, to avoid leaking information through timing.
Showing keys once
Display the full key only immediately after creation, with a copy button and a plain warning that it won't be shown again. If the customer loses it, they create a new one. This feels strict at first, but it's familiar to developers from major platforms, and it means a key can't be read later from the dashboard by anyone who gets into the account.
Giving customers control
Design the settings page around how customers actually use integrations:
- Multiple keys per account, each with a name ("Warehouse sync", "Zapier", "Website form").
- Scopes or permissions, such as read-only orders or write access to products, so one integration can't do everything.
- Last-used date, so customers can spot forgotten keys.
- Revocation that takes effect immediately.
- Test and live keys, clearly separated, if you have a sandbox.
- Expiry dates as an option, for temporary access such as a contractor's project.
To rotate without downtime, a customer creates a new key, updates their integration, checks it works, then revokes the old one. Allowing two active keys at once is what makes that possible.
Protecting the API itself
Keys identify the caller; they aren't the whole security story. OWASP's REST Security Cheat Sheet advises requiring API keys for every request to protected endpoints, returning a 429 Too Many Requests response when requests come too quickly, revoking keys when a client violates the usage agreement, and not relying on API keys alone to protect sensitive or high-value resources.
In practice:
- Accept keys only in a request header, never in URLs, which end up in logs and browser history.
- Require HTTPS for every request.
- Apply rate limits per key.
- Log which key made each request, without logging the key itself.
- For sensitive actions, consider stronger options such as OAuth or signed requests.
When a customer leaks a key
It will happen: a key pasted into a public repository, a forum post or a support email. Make it easy to respond:
- Customers can revoke and replace keys themselves.
- Your support team knows how to identify a key from its prefix and visible ending, and how to disable it on request.
- If you join a secret-scanning programme offered by code hosts, your prefix makes leaked keys detectable.
A worked example
Picture a hypothetical Melbourne inventory software company whose customers connected online shops and accounting tools with a single key per account, stored in plain text and visible in settings. A customer asked how to cut off a former contractor's integration without breaking their shop sync. The team redesigned keys: prefixed random keys, stored as keyed hashes, shown once, with names, read or write scopes and last-used dates. Existing keys kept working until customers replaced them, and the dashboard prompted each account to do so.
FAQ
Should API keys expire automatically?
Optional expiry is useful; forced short expiry often breaks unattended integrations. Let customers choose.
Can I let customers see their key again later?
It's safer not to. If you must, encrypt keys rather than hashing them, and accept the extra risk.
Is an API key enough for a public mobile app?
No. Anything shipped inside an app can be extracted. Use user authentication for app users.
How long should a key be?
Long enough to be unguessable; 32 random bytes encoded as text is a common choice.
If you're adding a customer-facing API and want the key handling right from day one, tell us about your platform.