docs: clarify totp_url block configuration (#6704)

Co-authored-by: Suchintan Singh <suchintan@skyvern.com>

docs/cloud/building-agents/configure-blocks.mdx

@@ -58,9 +58,13 @@ Browser-based blocks (Browser Task, Browser Action, Extraction, Login, File Down
 | **Max Steps Override** | Cap the number of AI reasoning steps |
 | **Disable Cache** | Skip cached script execution |
 | **TOTP Identifier** | Link TOTP credentials for 2FA handling |
-| **TOTP Verification URL** | Endpoint for fetching TOTP codes |
+| **TOTP Verification URL** | Endpoint this block polls when it needs a 2FA code |
 | **Error Code Mapping** | Map error conditions to custom error codes (JSON) |
 
+<Note>
+Set **TOTP Verification URL** on the block that may encounter 2FA. Top-level workflow run `totp_url` values do not automatically populate empty block fields.
+</Note>
+
 ---
 
 ## Browser Automation

docs/cloud/managing-credentials/totp-setup.mdx

@@ -171,7 +171,13 @@ This turns email-based 2FA into something nearly as automated as an authenticato
 
 ## Server-fetched codes (totp_url)
 
-Instead of pushing codes to Skyvern, you can have Skyvern pull them from your server. Pass `totp_url` when running a [task](/cloud/getting-started/run-from-code) or [agent](/cloud/building-agents/build-an-agent), and Skyvern will call your endpoint when it needs a verification code.
+Instead of pushing codes to Skyvern, you can have Skyvern pull them from your server. Skyvern calls your endpoint only when the automation reaches a page that asks for a verification code.
+
+<Warning>
+For saved agents or workflows, configure the endpoint on the block that performs the login. Open the browser, action, file download, or login block and set **TOTP Verification URL**. Passing `totp_url` only in the top-level workflow run request does not automatically populate a block whose **TOTP Verification URL** is empty.
+</Warning>
+
+If the endpoint changes per run, create a workflow parameter such as `totp_url`, set the block's **TOTP Verification URL** to `{{ totp_url }}`, and pass the URL in `parameters` when starting the run.
 
 Your endpoint must accept a POST request with `task_id`, `workflow_run_id`, and `workflow_permanent_id` in the body, and return:
 

docs/developers/credentials/handle-2fa.mdx

@@ -312,6 +312,12 @@ If `content` is longer than 10 characters, Skyvern's AI extracts the verificatio
 
 Instead of pushing codes to Skyvern, you implement an endpoint that Skyvern polls until a code is available.
 
+<Warning>
+For saved workflows or agents, configure the endpoint on the specific browser block that can encounter 2FA. Use the block's **TOTP Verification URL** field, or set that field to a workflow parameter such as `{{ totp_url }}` and pass the value in `parameters` when starting the run.
+
+Passing `totp_url` only at the top level of a workflow run does not automatically populate every block. If the block's **TOTP Verification URL** is empty, that block will not call your endpoint.
+</Warning>
+
 ### Step 1: Implement the endpoint
 
 Your endpoint must accept POST requests and return the verification code:
@@ -355,9 +361,9 @@ def verify_skyvern_request(request, api_key: str) -> bool:
     return hmac.compare_digest(signature, expected)
 ```
 
-### Step 3: Configure the login
+### Step 3: Configure the login or block
 
-Pass `totp_url` when running your login:
+For a one-off login task, pass `totp_url` in the login request:
 
 <CodeGroup>
 ```python Python
@@ -382,6 +388,22 @@ curl -X POST "https://api.skyvern.com/v1/run/tasks/login" \
 ```
 </CodeGroup>
 
+For a saved workflow or agent, configure the block that may see the 2FA prompt:
+
+1. Open the browser, action, file download, or login block that performs the login.
+2. Set **TOTP Verification URL** to your endpoint.
+3. If the endpoint changes per run, create a workflow parameter such as `totp_url`, set the block's **TOTP Verification URL** to `{{ totp_url }}`, and pass the URL in the run's `parameters`.
+
+```typescript TypeScript
+const body: SkyvernRunWorkflowRequest = {
+  workflow_id: "wpid_123",
+  parameters: {
+    totp_url: "https://your-server.com/totp-webhook",
+    // other workflow parameters...
+  },
+};
+```
+
 Skyvern polls your endpoint every 10 seconds until a code is returned or the timeout is reached.
 
 ---

docs/sdk-reference/helpers/download-files.mdx

@@ -56,7 +56,7 @@ for (const f of result.downloaded_files ?? []) {
 | `max_steps_per_run` | `int` | No | `None` | Cap AI steps. |
 | `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers. |
 | `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
-| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
+| `totp_url` | `str` | No | `None` | Endpoint Skyvern polls to fetch TOTP codes. |
 | `browser_address` | `str` | No | `None` | Connect to a browser at this CDP address. |
 | `max_screenshot_scrolling_times` | `int` | No | `None` | Number of screenshot scrolls. |
 | `waitForCompletion` (TS only) | `boolean` | No | `false` | Block until the download finishes. |

docs/sdk-reference/helpers/login.mdx

@@ -48,7 +48,7 @@ console.log(result.status);
 | `proxy_location` | `ProxyLocation` | No | `None` | Route browser traffic through a geographic proxy. |
 | `webhook_url` | `str` | No | `None` | URL to receive a POST when the login finishes. |
 | `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
-| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
+| `totp_url` | `str` | No | `None` | Endpoint Skyvern polls to fetch TOTP codes. |
 | `wait_for_completion` (Python) / `waitForCompletion` (TS) | `bool` | No | `False` | Block until the login finishes. |
 | `timeout` | `float` | No | `1800` | Max wait time in seconds. |
 | `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers. |

docs/sdk-reference/tasks/run-task.mdx

@@ -54,7 +54,7 @@ console.log(result.output);
 | `webhook_url` | `str` | No | `None` | URL to receive a POST when the run finishes. |
 | `error_code_mapping` | `dict[str, str]` | No | `None` | Map custom error codes to failure reasons. |
 | `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
-| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
+| `totp_url` | `str` | No | `None` | Endpoint Skyvern polls to fetch TOTP codes. |
 | `title` | `str` | No | `None` | Display name for this run in the dashboard. |
 | `model` | `dict` | No | `None` | Override the output model definition. |
 | `user_agent` | `str` | No | `None` | Custom User-Agent header for the browser. |

docs/sdk-reference/workflows/run-workflow.mdx

@@ -50,7 +50,7 @@ console.log(result.output);
 | `webhook_url` | `str` | No | `None` | URL to receive a POST when the run finishes. |
 | `title` | `str` | No | `None` | Display name for this run in the dashboard. |
 | `totp_identifier` | `str` | No | `None` | Identifier for TOTP verification. |
-| `totp_url` | `str` | No | `None` | URL to receive TOTP codes. |
+| `totp_url` | `str` | No | `None` | Workflow-level TOTP endpoint metadata. For saved agents/workflows, set **TOTP Verification URL** on the block that may encounter 2FA, or template that block field from a workflow parameter. |
 | `template` | `bool` | No | `None` | Run a template workflow. |
 | `user_agent` | `str` | No | `None` | Custom User-Agent header for the browser. |
 | `extra_http_headers` | `dict[str, str]` | No | `None` | Additional HTTP headers injected into every browser request. |