Remove a contact's two-factor
Requires customers:two_factor_lift — its own permission, held by owner and deliberately not by admin. This is the support act for a customer who lost both their phone and their recovery codes; every other way a second factor comes off is the contact’s own.
It is not customers:write on purpose. A merge is destructive and repairable — the merge record says what moved. This removes the control that makes holding somebody’s inbox insufficient to reach their account, and nothing stored afterwards repairs it. Granting it needs roles:manage, so an admin cannot hand it to themselves.
It is not a way in. No session is minted and no sign-in link is mailed: the person gets back in through a door they open themselves. What it does do, besides clearing the secret and deleting the recovery codes:
- every session of that contact is revoked, and published to
GET /v1/revocations/{publishable_key}in the same statement, so tokens already minted stop verifying within seconds rather than within their five minutes; - every outstanding one-time credential is spent — verification and reset tokens, magic links, email codes, in-flight two-factor challenges — because the other plausible reason for a lift is not a lost phone but an account that changed hands;
- the contact is emailed, in the class that is counted and never withheld. A silent removal of somebody’s second factor is exactly what an attacker holding your panel would want.
Whether the address was ever proven is untouched: that is a fact about the address, and removing a second factor does not unprove one.
The action is recorded in the audit log as contact.two_factor_lifted, with who did it and from where.
Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing. Absent, the session's default organization answers.
Path Parameters
Query Parameters
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test