Recovery
Recovery depends on which credentials remain available. A forgotten password can be replaced using a saved recovery code and a working authenticator. Losing the authenticator requires an administrator to verify the person's identity and authorize a new enrollment.
| They still have | What you use |
|---|---|
| The authenticator, and a saved recovery code | POST /auth/password/reset or mesgd user reset. See Enrollment |
| Neither a working authenticator nor a way to read its secret | An administrator handoff, then enrollment on /account |
A recovery code does not sign anyone in, and it does not replace the authenticator. An authenticator code by itself does not reset a password.
Replace a lost authenticator
mesgd provides the credential replacement mechanism, while the operator supplies the identity verification and a trusted delivery channel. Once that verification is complete:
- An administrator issues Recover OTP. The UI checkbox records that identity was verified. The API field is
identity_verified: true. mesgd stores a hash of the handoff code. The audit omits the code. - Deliver the code on a channel you already trust. It lasts ten minutes and works once.
- The person opens "Lost your authenticator?" on
/account, enters the username and the code, and optionally a new password. An invitation that has no linked provider requires a password. - mesgd returns a new authenticator enrollment: token, secret, otpauth URI, and a QR PNG when encoding works. That response is not a session.
- The person confirms with
POST /auth/signup/confirm. Only then do they receive a session and new recovery codes. The session records that they signed in through recovery plus the authenticator.
Old secrets, sessions, recovery codes, and unused handoffs are invalid. Provider links and public keys stay. If the handoff or the new enrollment expires, issue recovery again. Public signup cannot overwrite an account that is in recovery.
The HTTP call the person makes is POST /auth/recovery/enroll with user, recovery_token, and an optional new_password.
mesgd user recover USER writes a handoff file for the same flow. The JSON contains recovery_token. The reason recorded on the node is Node console identity recovery.
When no administrator can sign in
On the node, a trusted operator can issue the same handoff for a configured administrator name:
mesgd_http_auth:bootstrap_recovery(<<"operator@example.com">>,
<<"Verified recovery support case 123">>).The call returns the short-lived code. It does not return an authenticator secret or a session. It accepts only configured administrator names. This call is not an HTTP route. Keep the same identity check and the same private delivery.
bootstrap_admin/1 creates the first administrator enrollment from the node shell. Confirm that enrollment with /auth/signup/confirm. Keep at least two administrators so this path stays rare.