Playbook, developer tools company
The word reset covers two things here and one of them cannot wait
Two messages arrive under this heading with almost nothing in common. One is planned: somebody needs to replace a credential without their traffic failing during the swap, which is a documented procedure with an overlap built into it. The other is a token that has just been spotted in a public commit, where the only fact that matters is how quickly it stops working. Handling the second like a forgotten password is the failure to design against.
Why this is not the general answer
The handling pattern for password resets holds across every trade. What follows is the part that does not.
- The reset people ask for is usually a credential rotation rather than a sign in problem, and the interesting part is doing it without dropping requests, which needs two credentials valid at once and a documented overlap window.
- An exposed credential is an urgent security event rather than an account recovery, so the first clause of the reply should name revocation, and the register should not match the one used for somebody who forgot a password.
- A credential committed to a repository is not made safe by deleting the commit, because the history may already have been cloned or indexed elsewhere, and readers regularly believe the opposite with real conviction.
- Signing in to a dashboard and authenticating to the interface are different systems with different failures, and readers use one word for both, so establishing which one broke is the first move rather than a clarification.
How it arrives
- we pushed a token to a public repo what do we do first
- how do we rotate a credential with no downtime
- can two credentials be live at once during a swap
- does rotating invalidate the old one immediately
- i deleted the commit is the token safe now
- reset the credential our nightly job uses
What has to be indexed for this to work
| The rotation procedure, written as a sequence with the overlap in it | Issue the replacement, deploy it, confirm traffic has moved, retire the old one. The overlap is the entire value of the document, because without it rotation reads as a deliberate outage and people quietly stop doing it. |
|---|---|
| What to do about an exposed credential, with the order stated | Revoke first, investigate second, and a plain sentence saying that removing a commit does not undo the exposure. Write it as an ordered instruction, because the person reading it is not calm and will follow whatever is numbered. |
| How to tell whether traffic is still using the old credential | Whatever your product exposes, a last used time, a per credential counter, or nothing at all. If it is nothing, publish that, because the assumption that the check exists is what makes people postpone the retire step indefinitely. |
| The difference between dashboard sign in and interface authentication | Which system a given rejection belongs to and what each one looks like when it fails. Readers say reset for both, and the two have no steps in common, so an answer aimed at the wrong one wastes the whole exchange. |
The reply
If a credential has been exposed publicly, revoke it before anything else. Deleting the commit does not undo the exposure, because the history may already have been cloned or indexed, and the exposure note sets out the order to work in [1]. For a planned change, the rotation procedure issues a replacement while the existing credential is still valid, so you deploy the new one, confirm traffic has moved onto it and only then retire the old [2]. I cannot revoke, issue or check a credential. If you need one dealt with now, leave your name, your work email and the organisation name, and say in the message that this is an exposed credential so it is read as that.
Revocation goes in the first clause, because in the urgent version every later sentence is time somebody does not have. Contradicting the belief about deleting the commit is the single most useful thing on the page and it has to be stated rather than implied. Asking the reader to label the handover is the only prioritisation mechanism available, and it works because a person reading a queue can see the word.
Where it stops
The trigger. The reader reports an exposed or possibly exposed credential, or asks for one to be revoked, reissued or checked for use.
Revoking a credential needs somebody who can reach the account, and I cannot do it from here. Leave your name, your work email and the organisation name, and say clearly that this is an exposed credential so it is picked up as urgent rather than queued behind ordinary questions.
It stops answering before it guesses, says who will pick it up, and asks for the one thing that makes a reply possible. Nothing about it reads as a dead end.
Never say this here
Out of bounds
- Never say a credential has been revoked, rotated or reissued, because nothing here changes any credential.
- Never say an exposed credential is probably fine, or that removing the commit has dealt with it.
- Never tell somebody a credential is still valid, or that it has not been used by anybody.
- Never suggest keeping an old credential live beyond the documented overlap in order to avoid an outage.
Questions
- Should an exposure be handled differently from everything else?
- In wording, yes. The reply leads with the action, drops the pleasantries and asks the reader to label the handover. It cannot prioritise anything itself, so the label is the mechanism, and it works because somebody scanning a queue can act on it.
- Can it check whether a leaked credential has been used?
- No. It has no view of any request, any log or any account. Saying so immediately beats hedging, because the reader is deciding whether to declare an incident and a vague answer delays that decision by minutes that matter.
- Our rotation guide has no overlap step. Does that matter?
- It is the reason your customers do not rotate. Without a documented overlap, rotation reads as a planned outage, so it gets postponed indefinitely and then has to be done in a hurry on the worst possible day.
Keep reading
- Everything for a developer tools companyOn a docs site an assistant competes with search, not a phone line. Version skew, deprecations and error strings decide whether it earns its place.
- Handling password resets in generalAn assistant cannot reset anything. It can walk somebody through your real flow and name the step that usually breaks.
- Cancelling ends the commercial edition, not necessarily the softwareAnnual terms, a credential that stops authenticating on a date, and an open source core somebody keeps running. What can honestly be stated.
- The units were consumed, and the customer still wants the money backOverage on units that were genuinely delivered is not a billing error. What can be explained about caps, and why a person decides the rest.
- The first sign of a billing problem is a status code at four in the morningA billing suspension ends up as a rejected call in somebody's alerting. The retry schedule and the error string are the whole answer.
Try it on your own material
Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.