> ## Documentation Index > Fetch the complete documentation index at: https://docs.userkit.dev/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /api-reference/openapi.json delete /v1/organization/contacts/{id}/two-factor openapi: 3.1.0 info: title: UserKit API version: 1.0.0 description: >- The HTTP surface of UserKit. Two planes share one API. The **staff plane** is what a human uses in the panel: users, organizations, roles, members, keys. The **customer plane** is what a developer's own product uses: contacts, identities, hosted or federated sign-in. Every error answers the same envelope — `{"error": {"code", "message"}}`. The `code` is a stable contract to branch on; the `message` is for a person and may change. servers: - url: '{baseUrl}' description: The API host. variables: baseUrl: default: https://api.userkit.dev description: Base URL of the API, no trailing slash. security: - sessionToken: [] tags: - name: Authentication description: >- Public sign-up, sign-in, two-factor and password recovery for staff accounts. - name: Session description: >- The active session: who the caller is, which organization they are in, and signing out. - name: Account description: The caller's own account — profile, password, sessions, avatar. - name: Two-factor description: >- TOTP setup, activation and recovery codes. Returns 501 when two-factor is unavailable on the server. - name: Organizations description: The organizations a user belongs to, and the active one. - name: Environments description: >- The live and test environments seeded with every organization, and their identity settings. - name: Members description: Memberships and invitations. - name: Roles description: Roles and the permission catalogue they draw from. - name: Audit log description: >- What staff did inside an organization. Append-only, and read behind its own permission. - name: API keys description: Secret keys (`uk_sk_…`) and publishable keys (`uk_pk_…`). - name: Contacts (staff session) description: >- The staff view of the customer plane, opened by a staff session. Reads take `?environment=` as an explicit view parameter. - name: Contacts (API key) description: >- The machine surface, authenticated by an API key. The environment is the key's environment and cannot be named by the caller. - name: Customer plane description: >- Called from the developer's own pages with a publishable key: boot, magic link, and the contact's own session. - name: Hosted auth description: >- Sign-up, sign-in, verification and recovery for contacts, when UserKit owns the account. - name: Customer teams description: >- A customer is a team. Its roster, its invitations and its two roles — owner and member — administered by the contact's own session. The active customer travels in `X-Customer-Id`. - name: Webhooks description: >- Outbound webhooks: endpoints, the published event catalogue, the delivery log, replay and test sends. Never gated by a plan — webhooks are a developer primitive. - name: Catalogue description: >- The plans, prices and features **you** sell to your own customers. Per environment, a price per currency, and `recurring` or `one_time`. Distinct from the plan you are on with UserKit, which is `GET /v1/organization/entitlements`. - name: Subscriptions description: >- What one of **your** customers is paying you, mirrored from the gateway that charges them. The gateway is the truth about money — it holds the schedule, runs the retries and decides what a proration is worth — so these routes ask it to change something and answer with what it then said. `provider_synced_at` is how stale the copy admits to being. - name: Provider webhooks description: >- Where a payment provider delivers to. Not a surface you call — it is a URL you paste into the provider's dashboard, which is why it sits outside `/v1`: a version bump must never mean editing a setting in somebody else's product. Signed with the secret of the connection named in the path, and safe to retry. - name: Entitlements description: >- What one of **your** customers may do, resolved: the plan their subscription carries, plus the overrides you promised them on top. This is the read your own gate calls, so it is cached and answers in one round trip. It is a different question from `GET /v1/organization/entitlements`, which is the plan **you** are on with UserKit — two catalogues, same word, different money. paths: /v1/organization/contacts/{id}/two-factor: delete: tags: - Contacts (staff session) summary: Remove a contact's two-factor description: >- 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. operationId: liftContactTwoFactor parameters: - $ref: '#/components/parameters/OrganizationHeader' - name: id in: path required: true schema: type: string format: uuid - $ref: '#/components/parameters/EnvironmentQuery' responses: '200': description: Removed. content: application/json: schema: type: object properties: contact: $ref: '#/components/schemas/Contact' sessions_revoked: type: integer description: >- How many sessions the removal ended — worth saying out loud on the call: every device was signed out. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: >- `two_factor_disabled` — this contact does not have two-factor enabled. Deliberately not a no-op: a 200 here would record an action that did not happen, and it is what makes two operators clicking together produce one notice to the contact rather than two. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: OrganizationHeader: name: X-Organization-Id in: header required: false schema: type: string description: >- 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. EnvironmentQuery: name: environment in: query required: false schema: type: string enum: - live - test default: live description: >- 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. schemas: Contact: type: object description: One of the developer's own users — anonymous or identified. properties: id: type: string format: uuid name: type: - string - 'null' email: type: - string - 'null' avatar_url: type: - string - 'null' identified: type: boolean description: Whether this contact is more than a visitor. email_verified: type: boolean description: >- Whether the ADDRESS was proven — by a verification link, a reset link or a magic link. Distinct from a session's `verified` flag. two_factor_enabled: type: boolean description: >- Whether this contact demands a second factor. Every path that mints a session honours it, not only the password one — so an account screen reads this to decide between offering enrolment and offering to turn it off. `DELETE /v1/organization/contacts/{id}/two-factor` is the only way it comes off that is not the contact's own act. password_breached: type: boolean description: >- The password this contact signs in with was found in a public breach corpus. Sign-in is never refused because of it — the check runs after the fact, and the contact is emailed once, in your organization's name. Setting a new password clears it. attribution: $ref: '#/components/schemas/Attribution' first_seen_at: type: string format: date-time last_seen_at: type: string format: date-time created_at: type: string format: date-time Error: type: object description: Every error in this API answers this envelope. properties: error: type: object properties: code: type: string description: Stable. Branch on this. message: type: string description: For a person. May change. required: - code - message required: - error example: error: code: forbidden message: your role does not allow this action Attribution: type: object description: >- First touch, captured on the visitor at first load and preserved through a merge. All fields optional; empty means unknown. properties: utm_source: type: - string - 'null' utm_medium: type: - string - 'null' utm_campaign: type: - string - 'null' utm_term: type: - string - 'null' utm_content: type: - string - 'null' referrer: type: - string - 'null' landing_page: type: - string - 'null' responses: Unauthorized: description: >- `unauthorized` — missing, malformed or expired credential. A well-formed credential from the wrong family says so: "this endpoint expects a staff session token, not an organization API key". content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: '`forbidden` — your role does not allow this action.' content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: >- `not_found`. Also the answer for a resource that exists in another organization or environment — the 404 never reveals which. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: sessionToken: type: http scheme: bearer description: >- A staff session token, `uk_st_…`. Minted by sign-up, sign-in or the two-factor exchange. ````