Insights · Nov 11, 2026 · 4 min read · FAQ

API keys for customers: shown once, scoped and easy to revoke

Show each key once and keep only a hash, add a prefix scanners can spot, scope keys to one workspace, and make rotation and revocation easy.

CUSTOMER API KEYSKeys your customers manage SELLWRIGHT

Once customers connect your product to their own tools, someone asks for an API key. The quick version is one key per account, stored as plain text, visible forever and allowed to do everything. It works until a key turns up in a public repository and nobody can tell which key leaked or what it touched. OWASP's API Security Top 10 says API keys should authenticate API clients, not users, so treat each key as a credential for one program.

How should a new key be created and stored?

Generate it on the server, show it once and keep only a hash. OWASP's Multi-Tenant Security Cheat Sheet asks for API credentials from a cryptographically secure random generator with at least 128 bits of entropy, returned once and stored as a hash, never as plain text. For a high-entropy random key, it says SHA-256 is enough. A leaked database backup then holds no working keys.

Shown once:  yourapp_live_4fK9xQ2...

Stored row:  id, workspace_id, name, scopes
             display_prefix  yourapp_live_4fK9
             key_hash        SHA-256 of full key
             created_by, created_at,
             last_used_at, expires_at, revoked_at

In AgencyPilotHQ, our own Next.js SaaS, keys start with apk_live_, belong to one agency and are stored as a SHA-256 hash, with only the first few characters kept for display.

Why should every key carry a visible prefix?

So people and secret scanners can recognise your keys on sight. GitHub starts its tokens with a prefix for the token type, such as ghp_ for a classic personal access token and github_pat_ for a fine-grained one. Stripe's live secret, restricted and publishable keys start with sk_live_, rk_live_ and pk_live_, and the sandbox versions use _test_, so the mode shows at a glance.

The prefix pays off when a key leaks. Providers in GitHub's secret scanning partner program register a regular expression for their key format, and matches in public repositories and public npm packages are sent to the provider. GitHub advises treating every reported secret as public and compromised. Its suggested format for identifiable secrets is a unique prefix, a high-entropy random string and a 32-bit checksum.

What should one key be allowed to do?

Only the job it was made for, inside one workspace. OWASP asks for API credentials bound to explicit tenants, environments and permission scopes. Stripe's restricted keys show the pattern: each resource gets None, Read or Write, the default is None, and Stripe suggests a separate key for each service. The create-key form needs:

  • A name, so "Zapier sync" and "nightly export" are easy to tell apart.
  • The workspace, taken from where the key was created, never from the request.
  • Scopes, starting at read-only, with write access added area by area.
  • Test or live, with different prefixes, so a test key never touches real data.
  • An optional expiry date.

Tie the key to the workspace, not the person who made it, and check its scopes on the server, as in how we design roles and permissions.

How do customers rotate or revoke a key?

Allow two active keys at once, and make revoking take effect on the next request. Two keys let a customer deploy the new one, watch the old one go quiet, then revoke it with no downtime. Stripe builds this in: after a rotation, the old and new keys both work for up to 7 days, and Stripe advises expiring the old one only once its request logs show no traffic.

Revoking needs no grace period. Because each request looks up the key's hash, marking the row revoked blocks the very next call, as long as you don't cache lookups. OWASP's Secrets Management Cheat Sheet says secrets that are no longer needed or may be compromised must be revoked.

What should the key screen show and log?

For each key: its name, display prefix, scopes, who created it and when, when it was last used and when it expires. The last-used date makes clean-up safe: unused keys can go, and busy ones get checked before anyone revokes them.

Behind the screen, keep an audit trail. OWASP's Secrets Management Cheat Sheet lists what to record at a minimum, including when a secret was used and by whom or what, attempts to reuse expired secrets and authentication errors. Record every creation, rotation and revocation with the person who did it, and never log the key itself: OWASP says secrets should never be logged.

How should keys be sent, and how often can they be used?

In a request header over HTTPS, never in a URL, and only from servers. OWASP's REST Security Cheat Sheet keeps API keys out of URLs because a URL can be captured in web server logs, and RFC 6750, written for OAuth bearer tokens, prefers the Authorization header. Keep secret keys out of front-end code too: Stripe treats only its publishable keys as safe outside your back end, and OWASP's Key Management Cheat Sheet says API keys should never be embedded in build artifacts.

Then limit each key. OWASP's API Security Top 10 asks for a limit on how often a client can call the API, and its REST cheat sheet says to return 429 Too Many Requests when calls come too fast. Count per key and per workspace, so one runaway script slows only itself, and send a Retry-After header so clients know when to try again.

Where to start

Hold your current settings page against this article: shown once, hashed, prefixed, scoped, two keys during rotation, instant revocation, last-used dates, header only and rate limited. Our web app and SaaS development service builds the key screen and the checks behind it, and designing a SaaS audit log covers the trail behind every key change.

FAQ

Frequently asked questions

Can customers see their API key again after creating it?

Not if you store only a hash, and that is the point. The list shows the display prefix so they can find the right key, and a lost key is replaced, not recovered. Stripe works this way: a live secret key you create yourself can't be revealed after you've seen it once, and Stripe says to rotate or delete a lost key and create another.

Is SHA-256 enough to store API keys, or do we need bcrypt?

For keys your server generates, SHA-256 is enough. OWASP's Multi-Tenant Security Cheat Sheet says an approved hash such as SHA-256 suits a high-entropy random key, but does not protect low-entropy or user-chosen secrets, which belong under its password storage guidance. So generate every key yourself and never let customers choose the value.

Should API keys expire automatically?

Offer an expiry date and suggest one, but let the customer choose it. OWASP's Secrets Management Cheat Sheet says secrets should expire after a defined time where possible, and that applications should check a secret is still active before trusting it. GitHub recommends setting an expiration on personal access tokens. Email workspace admins before a key expires so no integration stops without warning.

What should we do when a customer's key leaks?

Revoke it at once, then help the customer replace it. GitHub's advice for a leaked credential is to generate a new one, replace the old one everywhere it is used, and delete the old one. Then check the leaked key's recent requests in your logs to see what it touched, and tell the workspace owner what you found.

Do we need OAuth instead of API keys?

Not for a customer's own scripts and server integrations, where API keys fit well. OAuth earns its place when other companies' apps act for many of your customers, because each customer approves the app's limited access and can later withdraw it. On GitHub, revoking an app's authorization also revokes every token tied to it. OWASP adds that API keys alone shouldn't guard high-value resources.

Should a key be locked to certain IP addresses?

Offer it as an option for customers whose servers have fixed addresses. Stripe's access policies, for example, can limit a key to specific IPv4 addresses or CIDR ranges, block requests from anywhere else and notify the account. Customers on platforms with changing addresses may not be able to use an allowlist, so keep it optional rather than required.

Next step

Ready for a website that sells?

Book a short call. We will look at your current site, agree what matters most and send a written scope with a fixed quote.

Book a callOr write to hello@sellwrightstudio.com