Resources · codebook
A four-step method for getting every key, token and secret in a small software estate under control: inventory from the deployed source, classify into five kinds, apply one test to decide what needs a copy, and write down what breaks when each is replaced.
Nobody sets out to keep a text file of unlabelled random strings. It happens because credentials arrive one at a time, over months, each one urgent, and none of them announce what kind of thing they are.
By the time there are a dozen, nobody can say which are live, which are dead, and which were never secret to begin with. The rotation that should happen does not, because nobody knows what it would break.
The fix is not more discipline. It is a classification exercise, done once, that turns every future credential decision into a lookup.
Four steps, one afternoon for a small estate.
Step 2 does the work. Everything after it follows mechanically.
The word "token" is doing five different jobs, which is exactly why the values blur together in a notes file. They differ on who made it, who can read it back, and what happens when it changes.
A shared secret you generate and can never read back. An API key a vendor issues and shows once. An OAuth token a service hands your app after a user clicks Allow, which you never see at all. A minted key your own app creates and stores as a one-way hash. And an identifier, which names a resource, carries no permission, and belongs in your committed config.
Place a value in one of those boxes and the correct handling stops being a judgement call.
Two patterns recur, and neither shows up in a configuration file.
The first is a silent fail-open: a check written to let traffic through when its secret is missing, so a configuration mistake never blocks a real customer. Usually the right call — and it means a missing secret produces no visible symptom at all.
The second is a coupled pair: an encryption key and the data encrypted under it. Rotating the key does not lock you out temporarily, it makes the data permanently unreadable. Nobody would guess that from the credential's name, which is precisely why blast radius belongs in writing.
A config file lists what was intended. The source shows what is read. In an estate that has been iterated on, those drift apart within months.
Start on The Five Kinds — that tab is the part that transfers to any stack, any cloud, any language.
Then Worked Example, which runs the method end to end on an illustrative four-service estate and shows the shape of the result: of fourteen credential-shaped values, three belong anywhere other than the machine.
Handling Rules carries the practical payoff — recipes that generate a secret without ever displaying it, and a one-line request that tells you whether an old value is still alive rather than leaving you to guess.
Run It Yourself is the procedure, with the commands, if you want to do this on your own systems.
