Skip to content

Automate browser based workflows with AI

docs/fix: update TOTP docs, SDK reference, light mode logo, and broken API key links (#5150)

Ritik Sahnid57ced394f48
diff --git a/docs/cloud/managing-credentials/totp-setup.mdx b/docs/cloud/managing-credentials/totp-setup.mdx
index f4ccfd5d2..30ac9f1a5 100644
--- a/docs/cloud/managing-credentials/totp-setup.mdx
+++ b/docs/cloud/managing-credentials/totp-setup.mdx
@@ -156,12 +156,85 @@ 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](/running-automations/extract-structured-data) or [workflow](/multi-step-automations/build-a-workflow), and Skyvern will call your endpoint when it needs a verification code.
+
+Your endpoint must accept a POST request with `task_id`, `workflow_run_id`, and `workflow_permanent_id` in the body, and return:
+
+```json
+{
+ "verification_code": "123456"
+}
+```
+
+Validate the `x-skyvern-signature` header to confirm the request came from Skyvern:
+
+```python
+import hashlib, hmac
+
+def validate_skyvern_request(request) -> bool:
+ signature = request.headers["x-skyvern-signature"]
+ payload = request.body() # bytes
+ expected = hmac.new(
+ SKYVERN_API_KEY.encode("utf-8"),
+ msg=payload,
+ digestmod=hashlib.sha256,
+ ).hexdigest()
+ return signature == expected
+```
+
+---
+
+## Magic links (one-time login links)
+
+Some sites use one-time login links instead of numeric codes. Skyvern supports these by splitting the flow into two steps:
+
+1. **Trigger the magic link** — Run a task that initiates the login. The site emails a one-time link.
+2. **Use the link** — Monitor the inbox (e.g., via Zapier), extract the URL, then start a new task with that URL as the starting point.
+
+```python
+# Step 1: Trigger the magic link email
+await client.run_task(
+ prompt="Click 'Sign in with email link' and enter [email protected]",
+ url="https://app.example.com/login",
+ wait_for_completion=True,
+)
+
+# Step 2: Your email monitor extracts the magic link URL, then:
+await client.run_task(
+ prompt="Complete the onboarding form after login",
+ url=magic_link_url, # The one-time URL from the email
+ wait_for_completion=True,
+)
+```
+
+The magic link URL becomes the `url` parameter for the second task — Skyvern opens it directly, which logs the user in, and then continues with the rest of the automation.
+
+---
+
## Viewing past codes
The table below the push form shows all 2FA codes your organization has received: identifier, extracted code, source type, associated workflow run, and timestamps. Filter by identifier, OTP type (numeric code vs. magic link), and number of results per page.
Use this for auditing and debugging: confirming that a code was received and delivered to the right run.
+### Listing codes via API
+
+```bash
+curl -X GET "https://api.skyvern.com/v1/credentials/[email protected]&limit=10" \
+ -H "x-api-key: $SKYVERN_API_KEY"
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `totp_identifier` | Filter by identifier (email, phone, etc.) |
+| `workflow_run_id` | Restrict to a specific workflow run |
+| `otp_type` | Filter by `totp` or `magic_link` |
+| `limit` | Number of records (default 50, max 200) |
+
+Returns a list ordered newest first. Only codes created within the last 10 minutes (configurable via `TOTP_LIFESPAN_MINUTES`) are returned.
+
<CardGroup cols={2}>
<Card
title="Password Credentials"
diff --git a/docs/debugging/observability-with-laminar.mdx b/docs/debugging/observability-with-laminar.mdx
index 953b82eee..1d0e876e5 100644
--- a/docs/debugging/observability-with-laminar.mdx
+++ b/docs/debugging/observability-with-laminar.mdx
@@ -34,7 +34,7 @@ npm install @skyvern/client @lmnr-ai/lmnr
</CodeGroup>
You will also need:
-- A **Skyvern API key** — get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/api-keys)
+- A **Skyvern API key** — get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/)
- A **Laminar API key** — sign up at [lmnr.ai](https://www.lmnr.ai/) and create a project
---
diff --git a/docs/docs.json b/docs/docs.json
index 39d848a0e..2bdad86c1 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -27,7 +27,7 @@
}
},
"logo": {
- "light": "/logo/light.png",
+ "light": "/images/skyvern_logo_blackbg.png",
"dark": "/logo/dark.png",
"href": "https://skyvern.com"
},
@@ -236,7 +236,7 @@
"primary": {
"type": "button",
"label": "Get API Key",
- "href": "https://app.skyvern.com/settings/api-keys"
+ "href": "https://app.skyvern.com/settings/"
}
},
"footer": {
diff --git a/docs/integrations/cli.mdx b/docs/integrations/cli.mdx
index ede1058a9..525e1ee39 100644
--- a/docs/integrations/cli.mdx
+++ b/docs/integrations/cli.mdx
@@ -258,7 +258,7 @@ You can also pass it directly:
skyvern credentials add --api-key YOUR_KEY
```
-Get an API key from [Settings](https://app.skyvern.com/settings/api-keys) in the Skyvern dashboard.
+Get an API key from [Settings](https://app.skyvern.com/settings/) in the Skyvern dashboard.
</Accordion>
<Accordion title="No active browser session">
diff --git a/docs/integrations/make.mdx b/docs/integrations/make.mdx
index 0d479161a..5ca9432e2 100644
--- a/docs/integrations/make.mdx
+++ b/docs/integrations/make.mdx
@@ -35,7 +35,7 @@ Connect Skyvern to 2,000+ apps through Make. Trigger browser automations from an
</Step>
<Step title="Connect your account">
- Click **Create a connection** and paste your API key from [Settings](https://app.skyvern.com/settings/api-keys).
+ Click **Create a connection** and paste your API key from [Settings](https://app.skyvern.com/settings/).
<Frame>
<video
diff --git a/docs/integrations/n8n.mdx b/docs/integrations/n8n.mdx
index 5a64ccebe..66274e3e1 100644
--- a/docs/integrations/n8n.mdx
+++ b/docs/integrations/n8n.mdx
@@ -32,7 +32,7 @@ Connect Skyvern to n8n's open-source automation platform. Trigger browser automa
</Step>
<Step title="Connect your account">
- Click *Select credential* → "Create new credential" and paste your API key from [Settings](https://app.skyvern.com/settings/api-keys).
+ Click *Select credential* → "Create new credential" and paste your API key from [Settings](https://app.skyvern.com/settings/).
</Step>
<Step title="Configure">
diff --git a/docs/integrations/workato.mdx b/docs/integrations/workato.mdx
index c1180083b..2a9df200b 100644
--- a/docs/integrations/workato.mdx
+++ b/docs/integrations/workato.mdx
@@ -40,7 +40,7 @@ Connect Skyvern to Workato's enterprise automation platform. Trigger browser aut
</Step>
<Step title="Connect your account">
- Paste your API key from [Settings](https://app.skyvern.com/settings/api-keys) and save the connection.
+ Paste your API key from [Settings](https://app.skyvern.com/settings/) and save the connection.
<Frame>
<img src="/images/workato/s1img7.png" alt="Connect Skyvern account in Workato" />
diff --git a/docs/integrations/zapier.mdx b/docs/integrations/zapier.mdx
index 24f04319b..249af0445 100644
--- a/docs/integrations/zapier.mdx
+++ b/docs/integrations/zapier.mdx
@@ -37,7 +37,7 @@ Connect Skyvern to 7,000+ apps through Zapier. Trigger browser automations from
</Step>
<Step title="Connect your account">
- Click *Sign in* on the left panel and paste your API key from [Settings](https://app.skyvern.com/settings/api-keys).
+ Click *Sign in* on the left panel and paste your API key from [Settings](https://app.skyvern.com/settings/).
<Frame>
<video
diff --git a/docs/sdk-reference/complete-reference.mdx b/docs/sdk-reference/complete-reference.mdx
index 53224569c..8f6e43311 100644
--- a/docs/sdk-reference/complete-reference.mdx
+++ b/docs/sdk-reference/complete-reference.mdx
@@ -47,6 +47,264 @@ All methods are async. Use `await` inside `async def`, with `asyncio.run()` as e
---
+## Browser control
+
+The SDK can launch and connect to browsers directly, giving you a Playwright-compatible page with AI capabilities layered on top. This is separate from the API-level browser session methods — here you get a live `SkyvernBrowser` and `SkyvernBrowserPage` you can script against.
+
+### `launch_local_browser`
+
+Launch a local Chromium browser with CDP enabled. Requires local mode (`Skyvern.local()`).
+
+```python
+browser = await client.launch_local_browser(
+ headless: bool = False, # Run headless or with a visible window.
+ port: int = 9222, # CDP port.
+ args: list[str] | None = None, # Extra Chromium flags.
+ user_data_dir: str | None = None,# Persistent profile directory.
+) -> SkyvernBrowser
+```
+
+### `connect_to_browser_over_cdp`
+
+Connect to any running browser via Chrome DevTools Protocol.
+
+```python
+browser = await client.connect_to_browser_over_cdp(
+ cdp_url: str, # e.g. "http://localhost:9222"
+) -> SkyvernBrowser
+```
+
+### `connect_to_cloud_browser_session`
+
+Connect to an existing cloud browser session by ID.
+
+```python
+browser = await client.connect_to_cloud_browser_session(
+ browser_session_id: str,
+) -> SkyvernBrowser
+```
+
+### `launch_cloud_browser`
+
+Create a new cloud browser session and connect to it.
+
+```python
+browser = await client.launch_cloud_browser(
+ timeout: int | None = None, # Minutes (5-1440). Default 60.
+ proxy_location: ProxyLocation | None = None,
+) -> SkyvernBrowser
+```
+
+### `use_cloud_browser`
+
+Reuse the most recent available cloud session, or create a new one if none exists.
+
+```python
+browser = await client.use_cloud_browser(
+ timeout: int | None = None,
+ proxy_location: ProxyLocation | None = None,
+) -> SkyvernBrowser
+```
+
+### Getting a page
+
+```python
+page = await browser.get_working_page() # Most recent page, or creates one
+page = await browser.new_page() # Always creates a new tab
+```
+
+Both return a `SkyvernBrowserPage` — a Playwright `Page` with AI methods added.
+
+---
+
+## Page-level AI methods
+
+`SkyvernBrowserPage` extends Playwright's `Page`. You can use all standard Playwright methods (`goto`, `fill`, `locator`, `screenshot`, etc.) plus these AI-powered methods.
+
+### `page.act`
+
+Perform an action described in natural language.
+
+```python
+await page.act(prompt: str) -> None
+```
+
+```python
+await page.act("Click the login button")
+await page.act("Select 'United States' from the country dropdown")
+```
+
+### `page.click` (AI-enhanced)
+
+Click an element using a CSS selector, an AI prompt, or both with fallback.
+
+```python
+await page.click(
+ selector: str | None = None, # CSS selector.
+ prompt: str | None = None, # Natural language target description.
+ ai: str | None = "fallback", # "fallback" (try selector, then AI) or None.
+ **kwargs, # Standard Playwright click options.
+) -> str | None
+```
+
+```python
+# Selector only
+await page.click("#submit-btn")
+
+# AI only
+await page.click(prompt="Click the 'Submit Order' button")
+
+# Selector with AI fallback
+await page.click("#submit-btn", prompt="Click the submit button")
+```
+
+### `page.extract`
+
+Extract structured data from the current page using AI.
+
+```python
+result = await page.extract(
+ prompt: str, # What to extract.
+ schema: dict | list | str | None = None, # JSON Schema for the output.
+ error_code_mapping: dict[str, str] | None = None,
+) -> dict | list | str | None
+```
+
+```python
+products = await page.extract(
+ prompt="Extract all products with name and price",
+ schema={
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {"type": "string"},
+ "price": {"type": "number"},
+ },
+ },
+ },
+)
+```
+
+### `page.agent.run_task`
+
+Run an AI task in the context of the current page. Always waits for completion.
+
+```python
+result = await page.agent.run_task(
+ prompt: str,
+ engine: RunEngine = RunEngine.skyvern_v2,
+ url: str | None = None, # Defaults to current page URL.
+ data_extraction_schema: dict | str | None = None,
+ max_steps: int | None = None,
+ timeout: float = 1800,
+ # Plus: model, webhook_url, totp_identifier, totp_url, title, error_code_mapping, user_agent
+) -> TaskRunResponse
+```
+
+### `page.agent.login`
+
+Run a login workflow in the context of the current page. Supports all credential types.
+
+```python
+# Skyvern credentials
+await page.agent.login(
+ credential_type=CredentialType.skyvern,
+ credential_id="cred_123",
+)
+
+# Bitwarden
+await page.agent.login(
+ credential_type=CredentialType.bitwarden,
+ bitwarden_item_id="item_id",
+)
+
+# 1Password
+await page.agent.login(
+ credential_type=CredentialType.onepassword,
+ onepassword_vault_id="vault_id",
+ onepassword_item_id="item_id",
+)
+
+# Azure Key Vault
+await page.agent.login(
+ credential_type=CredentialType.azure_vault,
+ azure_vault_name="vault_name",
+ azure_vault_username_key="username_key",
+ azure_vault_password_key="password_key",
+)
+```
+
+### `page.agent.download_files`
+
+Download files using AI navigation, in the context of the current page.
+
+```python
+result = await page.agent.download_files(
+ prompt: str,
+ url: str | None = None,
+ download_suffix: str | None = None,
+ download_timeout: float | None = None,
+ max_steps_per_run: int | None = None,
+ timeout: float = 1800,
+) -> WorkflowRunResponse
+```
+
+### `page.agent.run_workflow`
+
+Run a workflow in the context of the current page.
+
+```python
+result = await page.agent.run_workflow(
+ workflow_id: str,
+ parameters: dict | None = None,
+ timeout: float = 1800,
+) -> WorkflowRunResponse
+```
+
+### Full example
+
+```python
+from skyvern import Skyvern
+from skyvern.schemas.run_blocks import CredentialType
+
+async def main():
+ client = Skyvern(api_key="YOUR_API_KEY")
+ browser = await client.launch_cloud_browser()
+ page = await browser.get_working_page()
+
+ # Navigate and log in with AI
+ await page.goto("https://app.example.com")
+ await page.agent.login(
+ credential_type=CredentialType.skyvern,
+ credential_id="cred_123",
+ )
+
+ # Mix Playwright and AI
+ await page.click("#invoices-tab")
+ data = await page.extract(
+ prompt="Extract all invoice numbers and amounts",
+ schema={
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "invoice_number": {"type": "string"},
+ "amount": {"type": "number"},
+ },
+ },
+ },
+ )
+ print(data)
+
+ await browser.close()
+
+import asyncio
+asyncio.run(main())
+```
+
+---
+
## Imports
```python
@@ -591,3 +849,6 @@ print(run.output)
- Only workflow runs with `persist_browser_session=True` produce archives for profile creation.
- Session archiving is async — profile creation may need a short retry delay after a run completes.
- `engine` accepts `RunEngine` enum values: `skyvern_v1`, `skyvern_v2`, `openai_cua`, `anthropic_cua`, `ui_tars`.
+- `launch_local_browser` only works in local mode (`Skyvern.local()`). Cloud browser methods (`launch_cloud_browser`, `use_cloud_browser`, `connect_to_cloud_browser_session`) require cloud environment.
+- `page.agent` methods always wait for completion — they don't support `wait_for_completion=False`.
+- TypeScript SDK does not support browser control (local or cloud) — use the Python SDK for browser automation.
diff --git a/docs/sdk-reference/overview.mdx b/docs/sdk-reference/overview.mdx
index a70112178..1bd5f3b59 100644
--- a/docs/sdk-reference/overview.mdx
+++ b/docs/sdk-reference/overview.mdx
@@ -43,7 +43,7 @@ If you're inside a framework that already runs an event loop (FastAPI, Django AS
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
-| `api_key` | `str` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/api-keys). |
+| `api_key` | `str` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/). |
| `environment` | `SkyvernEnvironment` | `CLOUD` | Target environment. Options: `CLOUD`, `STAGING`, `LOCAL`. |
| `base_url` | `str \| None` | `None` | Override the API base URL. Use this for self-hosted deployments. |
| `timeout` | `float \| None` | `None` | HTTP request timeout in seconds. |
diff --git a/docs/ts-sdk-reference/overview.mdx b/docs/ts-sdk-reference/overview.mdx
index 47d324955..6285190e7 100644
--- a/docs/ts-sdk-reference/overview.mdx
+++ b/docs/ts-sdk-reference/overview.mdx
@@ -39,7 +39,7 @@ console.log(result.output);
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
-| `apiKey` | `string` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/api-keys). |
+| `apiKey` | `string` | — | **Required.** Your Skyvern API key. Get one at [app.skyvern.com/settings](https://app.skyvern.com/settings/). |
| `environment` | `SkyvernEnvironment \| string` | `Cloud` | Target environment. Options: `Cloud`, `Staging`, `Local`. |
| `baseUrl` | `string` | `undefined` | Override the API base URL. Use this for self-hosted deployments. |
| `timeoutInSeconds` | `number` | `60` | HTTP request timeout in seconds. |