start_2fa
Starts a two-factor authentication challenge for sensitive operations, sending a verification code via the selected channel and returning a session ID to poll for verification status.
Instructions
Start a two-factor authentication challenge for a sensitive operation. Sends a verification code via the chosen channel. Returns a session ID, and for messaging channels: deep_link, qr_code (base64 PNG), and qr_text (UTF-8 text QR for terminal display).
Agent usage — full 2FA flow: (1) Call start_2fa with the appropriate action_type and channel. (2) Present the challenge, and do NOT announce a message the server did not send: email is the ONLY channel it dispatches on. On telegram/whatsapp the user opens deep_link and sends the message themselves; on sms they send sms_message to a number from sms_dids; the response's own instructions field says which. On email, a 200 carrying requires_email_selection: true and available_emails means nothing was sent and no session exists — ask which address and call again with email_id. For telegram/whatsapp, pass deep_link to render_auth_link; for sms, show sms_message. Never hand qr_text to a link renderer — it is the link already rendered as QR art, so print it verbatim inside a fenced code block only when a real terminal needs the QR. (3) Poll get_2fa_status with the returned session_id until status is "verified" (the user enters the code on their device) or "expired". (4) If verified, proceed with the protected operation (e.g. create_api_key). If expired, inform the user and offer to restart. Typical channels: "telegram" or "email". For email, the user may receive a magic link instead of a code — the backend handles this automatically.
The user does not see tool results — most clients fold them away, render_auth_link's output included. Before you wait or poll, put what the user must act on into your own reply text: the link itself (not a sentence announcing it), the SMS text and number, or a note to check their inbox.
ACCESS: needs a Proof account. Set PROOF_API_KEY and restart this server, or sign in with start_login — a session opens this tool — then call this tool again.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| channel | Yes | Channel to receive the verification code | |
| targets | No | The ids the step-up is FOR — the grant is bound to exactly these and refused for any other request (`reason: target_mismatch`). revocation_bulk: the asset id you will pass to revoke_asset (one code per asset); phone_remove / email_remove: the phone or email record id; domain_remove: the domain id; profile_delete: the sub-account id; account_delete: your own user id (get_current_user). Leave out for the other action types. | |
| email_id | No | Specific email ID for email channel (optional) | |
| phone_id | No | Optional: specific UserPhone id for phone-channel 2FA | |
| single_use | No | Whether the grant is consumed on first use. Server forces true for destructive action types. Defaults to true. | |
| action_type | Yes | The sensitive action requiring 2FA: any action type the API documents | |
| ttl_seconds | No | Requested grant lifetime in seconds. Server caps to 300s for destructive action types, 86400s for configuration scopes. Defaults to 300 if omitted. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| No | The address the code went to, masked (`email` only) | ||
| status | No | ||
| channel | No | ||
| message | No | ||
| qr_code | No | Base64-encoded PNG QR code for `deep_link` | |
| qr_text | No | UTF-8 text QR for `deep_link`, for terminal/agent rendering | |
| sms_code | No | The short code the person texts (`sms` only) | |
| sms_dids | No | Our SMS numbers, one entry per region and always all three. A region with no number configured carries an empty `did` and no QR code. | |
| deep_link | No | Opens Telegram or WhatsApp with what the person sends (`telegram`, `whatsapp`) | |
| email_sent | No | `true` when the code was emailed (`email` only) | |
| expires_at | No | ||
| session_id | No | ||
| sms_message | No | The message to send (`sms` only) | |
| instructions | No | One line telling the person what to do | |
| available_emails | No | The addresses the code may go to; call again with one of their ids as `email_id` | |
| requires_email_selection | No | Always `true`: no session was started, pick an address and start again | |
| second_method_recommended | No | Present (true) when the step-up uses the channel the account signed in with, because the account has no other; adding a second channel is recommended |