Storing keys safely
What we store
| The 8-character prefix | in the clear. It identifies the row and is safe to log |
| The 32-character secret | an argon2id hash, never the secret itself |
So the secret exists in exactly two places: your secret store, and the one HTTP response that created it. We cannot show it to you again, and no support process can recover it. That is the point, and it is also the constraint you have to design around.
The prefix is the handle for everything else. Log it, put it in a support ticket, print it in a deployment banner. It identifies the key and grants nothing.
Where keys actually leak
In rough order of how often it happens:
Committed to a repository. Including a private one, which is still every person with read access, plus every fork, every clone on a laptop and the whole history after you delete the line. Removing a key from the tip of a branch does nothing; the commit still has it. Revoke it, do not rewrite history.
Written to logs. Usually by something well meaning that logs whole request headers or a whole config object on startup. Log the prefix if you need to log anything.
Pasted into a conversation. A support thread, a chat, a ticket, a screenshot of a terminal. If a key has been in any of those, treat it as exposed.
Shipped to a browser or a mobile app. Anything that reaches a user’s device is public, however it is obfuscated. A key in a client bundle is a key you have published.
Left in a decommissioned service. The server is gone and the key is not revoked, so it stays valid forever, because keys do not expire.
Storing one
Use your platform’s secret store. The environment’s own mechanism, a managed secret manager, or your orchestrator’s secrets. Not a file in the repository, and not a build argument baked into an image layer.
Inject at runtime, as an environment variable or a mounted secret. Read it once at startup.
Keep it out of your own error reporting. Exception trackers love to capture
local variables and request headers. Redact Authorization explicitly: that is
a one-line configuration in every tracker worth using and it closes a common
leak.
Different key per environment and per service. Not for secrecy, but for blast radius and attribution: a key shared by four services cannot be revoked without taking down four services, which is exactly the pressure that stops people revoking it when they should. See live and test keys.
Server-side only
Every key, live or test, is a server-side credential. There is no publishable key and no browser-safe variant.
If a browser or an app needs to trigger mail, it calls your backend and your backend calls Lockally. Your backend decides what that user may do; the key never leaves it. There is no configuration that makes a key safe to ship to a client.
Give each key as little as possible
The cheapest containment is a key that could not do much in the first place.
Scope to the job, not the account, and prefer
per-mailbox grants where they apply.
tenant:admin especially belongs only to something a human operates, because
it can create more keys.
See least privilege.
Notice when something changes
A new key emails the account’s alert address, with the label, prefix, scopes and creating IP, and never the secret. If one of those arrives that nobody meant to create, that is an incident, and the prefix in the mail is what you revoke.
It honours the account’s security-notification preference. Leave it on.
If a key is exposed
Revoke first and ask questions second. See after a suspected leak.