同步完整源码 - 2026-05-24

This commit is contained in:
xiaoxue
2026-05-24 23:27:44 +08:00
commit 4608c06bb3
366 changed files with 53434 additions and 0 deletions
+515
View File
@@ -0,0 +1,515 @@
---
title: Handle 2FA
subtitle: Configure two-factor authentication for automated logins
description: Configure two-factor authentication for Skyvern automations using TOTP secrets, pushed verification codes, pull-based endpoints, or magic links. Supports Bitwarden TOTP integration.
slug: developers/credentials/handle-2fa
keywords:
- TOTP
- 2FA
- totp_identifier
- totp_url
- authenticator
- email code
- SMS code
- magic link
- send_totp_code
- verification
---
Many websites require two-factor authentication (2FA) during login. Skyvern supports multiple 2FA methods to handle these flows automatically.
---
## Choose your method
Select the method that matches how you receive verification codes:
| Scenario | Recommended Method |
|----------|-------------------|
| You have the TOTP secret key | [Store TOTP secret](#method-1-store-totp-secret): Skyvern generates codes |
| Codes sent to email/SMS you can forward | [Push codes to Skyvern](#method-2-push-codes-to-skyvern) |
| Codes sent to a system you control | [Skyvern pulls from your endpoint](#method-3-skyvern-pulls-from-your-endpoint) |
| Passwordless/magic link auth | [Magic links](#method-4-magic-links) |
| Using Bitwarden with TOTP | [Password manager integration](#password-manager-totp) |
---
## Method 1: Store TOTP secret
**Best for:** Sites where you have access to the TOTP secret (the setup QR code or manual key).
When you enable 2FA on a website, you're typically shown a QR code or a secret key. Store this secret with your credential, and Skyvern generates valid codes automatically.
<CodeGroup>
```python Python
import os
from skyvern import Skyvern
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
credential = await client.create_credential(
name="Acme Portal Login",
credential_type="password",
credential={
"username": "user@example.com",
"password": "secure_password",
"totp": "JBSWY3DPEHPK3PXP", # Base32 secret from QR code
"totp_type": "authenticator",
},
)
```
```typescript TypeScript
import { SkyvernClient } from "@skyvern/client";
const client = new SkyvernClient({
apiKey: process.env.SKYVERN_API_KEY,
});
const credential = await client.createCredential({
name: "Acme Portal Login",
credential_type: "password",
credential: {
username: "user@example.com",
password: "secure_password",
totp: "JBSWY3DPEHPK3PXP",
totp_type: "authenticator",
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Portal Login",
"credential_type": "password",
"credential": {
"username": "user@example.com",
"password": "secure_password",
"totp": "JBSWY3DPEHPK3PXP",
"totp_type": "authenticator"
}
}'
```
</CodeGroup>
### TOTP types
| Type | Description |
|------|-------------|
| `authenticator` | Standard TOTP codes (Google Authenticator, Authy, etc.) |
| `email` | Codes sent via email that you'll push to Skyvern |
| `text` | Codes sent via SMS that you'll push to Skyvern |
<Tip>
Skyvern generates TOTP codes using standard 30-second windows. If the current code has less than 20 seconds remaining, Skyvern automatically uses the next code to ensure successful entry.
</Tip>
### Finding your TOTP secret
Most sites show the secret when you set up 2FA:
1. Go to your account's security settings
2. Click "Set up authenticator app"
3. Look for "Can't scan the QR code?" or "Manual entry"
4. Copy the secret key (usually Base32 format like `JBSWY3DPEHPK3PXP`)
<Note>
If you've already set up 2FA and don't have the secret, you may need to disable and re-enable 2FA to see the secret again. Contact [support@skyvern.com](mailto:support@skyvern.com) for help.
</Note>
---
## Method 2: Push codes to Skyvern
**Best for:** Codes sent to email or SMS that you can programmatically forward.
When your automation encounters a 2FA prompt, Skyvern polls for codes that you push via API. Your email or SMS forwarding system sends codes to Skyvern as they arrive.
### Step 1: Set up code forwarding
Configure your email or SMS to forward verification codes to Skyvern. Common approaches:
- **Email:** Gmail filter + Zapier webhook
- **SMS:** Twilio webhook to your server
- **Email:** AWS SES + Lambda function
<AccordionGroup>
<Accordion title="How to set up Email Forwarding with Zapier?">
This setup requires a Zapier Pro plan account.
<Steps>
<Step title="Create a Zapier Zap">
{/* TODO: Replace with actual video */}
<Frame>
<video
autoPlay
muted
loop
playsInline
className="rounded-xl"
src="/images/zapier-forwarding-setup.mp4"
></video>
</Frame>
1. Go to [zapier.com](https://zapier.com/app/home) and create a new Zap
2. In the newly created Zap draft, click the "Trigger" button
3. Click **Email by Zapier**
4. In the Email "Setup", pick **New Inbound Email** in the Trigger event selection. Click **Continue**
5. In Email "Configure", create an email address which will be used to forward emails for TOTP codes. Click **Continue**
6. Click the "Action" button and add **Webhooks by Zapier**
7. In the Setup, choose **POST** under the Action event selection. Click **Continue**
8. In the "Configure", set up these fields to make a POST request to Skyvern's TOTP API:
- **URL:** `https://api.skyvern.com/v1/credentials/totp`
- **Payload Type:** `json`
- **Data:**
- `totp_identifier`: choose **Raw To Email** after clicking the "+" sign
- `content`: choose **Body Plain** after clicking the "+" sign
- `source`: `email`
- **Headers:**
- `x-api-key`: your Skyvern API key
9. Click **Continue**
</Step>
<Step title="Add forwarding email and create a filter in Gmail">
Go to Gmail Settings → Forwarding and POP/IMAP → click **Add a forwarding address** → enter the Zapier email address you created. Complete any verification steps.
Then go to **Filters and Blocked Addresses**. Click **Create a new filter** and set up a filtering rule for your TOTP (2FA/MFA) emails. Click **Create filter**, check **Forward it to**, pick the Zapier email address, and update the filter.
<Frame>
<img src="/images/totp/create_email_forwarding.png" alt="Gmail forwarding filter" width="400"/>
</Frame>
</Step>
<Step title="Test it end to end">
Forward any previous TOTP email to the Zapier email address you created.
In Zapier, under the "Test" of the Webhooks action, send a request to test it out. If successful, you should see a "A request was sent to Webhooks by Zapier" message.
</Step>
</Steps>
</Accordion>
<Accordion title="How to set up SMS Forwarding with Twilio?">
Use a virtual phone number service like [Twilio](https://www.twilio.com/en-us/docs/usage/tutorials/how-to-use-your-free-trial-account) or [Plivo](https://www.plivo.com/) to receive SMS codes and forward them to Skyvern.
<Steps>
<Step title="Set up a Twilio phone number">
Create a Twilio account and provision a phone number. This number will receive the SMS verification codes.
</Step>
<Step title="Create a Twilio Function to forward codes">
In your Twilio console, create a new Function that forwards incoming SMS to Skyvern's TOTP API:
```javascript
// Twilio Function
exports.handler = async function(context, event, callback) {
const axios = require('axios');
await axios.post('https://api.skyvern.com/v1/credentials/totp', {
totp_identifier: event.To, // Your Twilio phone number
content: event.Body,
source: 'phone'
}, {
headers: {
'x-api-key': context.SKYVERN_API_KEY,
'Content-Type': 'application/json'
}
});
return callback(null, new Twilio.Response());
};
```
Add your `SKYVERN_API_KEY` as an environment variable in the Twilio Function configuration.
</Step>
<Step title="Configure the webhook">
In your Twilio phone number settings, set the **A Message Comes In** webhook to point to your Twilio Function URL.
</Step>
<Step title="Test it">
Send a test SMS to your Twilio number and verify the code appears in Skyvern:
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=YOUR_TWILIO_NUMBER" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</Step>
</Steps>
</Accordion>
</AccordionGroup>
### Step 2: Start the run with a TOTP identifier
When running your login, include a `totp_identifier` that matches what you'll use when pushing codes:
<CodeGroup>
```python Python
result = await client.login(
credential_type="skyvern",
url="https://portal.example.com/login",
credential_id="cred_xyz789",
totp_identifier="user@example.com", # Must match when pushing code
)
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks/login" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"credential_type": "skyvern",
"url": "https://portal.example.com/login",
"credential_id": "cred_xyz789",
"totp_identifier": "user@example.com"
}'
```
</CodeGroup>
### Step 3: Push the code when received
When the verification code arrives, push it to Skyvern:
<CodeGroup>
```python Python
await client.send_totp_code(
totp_identifier="user@example.com",
content="Your verification code is 123456", # Full email/SMS body
source="email",
)
```
```typescript TypeScript
await client.sendTotpCode({
totp_identifier: "user@example.com",
content: "Your verification code is 123456",
source: "email",
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"totp_identifier": "user@example.com",
"content": "Your verification code is 123456",
"source": "email"
}'
```
</CodeGroup>
<Note>
If `content` is longer than 10 characters, Skyvern's AI extracts the verification code automatically. You can send the full email or SMS body without parsing it yourself.
</Note>
---
## Method 3: Skyvern pulls from your endpoint
**Best for:** Environments where you control the system receiving 2FA codes and can expose them via an HTTP endpoint.
Instead of pushing codes to Skyvern, you implement an endpoint that Skyvern polls until a code is available.
### Step 1: Implement the endpoint
Your endpoint must accept POST requests and return the verification code:
**Request from Skyvern:**
```http
POST https://your-server.com/totp-webhook
x-skyvern-signature: <hmac-sha256-signature>
Content-Type: application/json
{
"task_id": "tsk_123456"
}
```
**Expected response:**
```json
{
"verification_code": "123456"
}
```
### Step 2: Verify request signatures
Skyvern signs all requests using HMAC-SHA256 with your API key. Verify the signature to ensure requests are authentic:
```python
import hmac
import hashlib
def verify_skyvern_request(request, api_key: str) -> bool:
signature = request.headers.get("x-skyvern-signature")
payload = request.body # bytes
expected = hmac.new(
api_key.encode("utf-8"),
msg=payload,
digestmod=hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
```
### Step 3: Configure the login
Pass `totp_url` when running your login:
<CodeGroup>
```python Python
result = await client.login(
credential_type="skyvern",
url="https://portal.example.com/login",
credential_id="cred_xyz789",
totp_url="https://your-server.com/totp-webhook",
)
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks/login" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"credential_type": "skyvern",
"url": "https://portal.example.com/login",
"credential_id": "cred_xyz789",
"totp_url": "https://your-server.com/totp-webhook"
}'
```
</CodeGroup>
Skyvern polls your endpoint every 10 seconds until a code is returned or the timeout is reached.
---
## Method 4: Magic links
**Best for:** Passwordless authentication systems that send one-time login links.
When a site uses magic links instead of passwords, push the link to Skyvern:
<CodeGroup>
```python Python
await client.send_totp_code(
totp_identifier="user@example.com",
content="https://portal.example.com/login?token=abc123xyz",
source="email",
)
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"totp_identifier": "user@example.com",
"content": "https://portal.example.com/login?token=abc123xyz",
"source": "email"
}'
```
</CodeGroup>
<Note>
Skyvern automatically detects URLs and classifies them as magic links. The automation will navigate to the link to complete authentication.
</Note>
For magic link flows, structure your workflow in two parts:
1. **Trigger the magic link**: Navigate to login and enter email
2. **Complete login**: Use the magic link as the starting URL for the next step
---
## Password manager TOTP
If you store TOTP secrets in Bitwarden or 1Password, Skyvern can retrieve both the password and TOTP code in a single request.
### Bitwarden
Store your TOTP secret in Bitwarden's authenticator field:
1. Open the vault item in Bitwarden
2. Click "Authenticator Key (TOTP)"
3. Enter your TOTP secret or scan the QR code
4. Skyvern retrieves both password and TOTP when using this credential
**Supported TOTP formats:**
- Raw secret: `JBSWY3DPEHPK3PXP`
- otpauth URI: `otpauth://totp/Example:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Example`
### 1Password
Store TOTP in 1Password's one-time password field:
1. Edit the login item in 1Password
2. Add a "One-Time Password" field
3. Enter the TOTP secret or scan the QR code
4. Reference the item in your Skyvern workflow
---
## Multi-field TOTP entry
Some sites split TOTP codes across multiple input fields (one digit per box). Skyvern handles this automatically:
1. Detects multi-field TOTP layouts
2. Enters the same code across all fields
3. Caches the code to prevent requesting a new one mid-entry
<Note>
No special configuration needed. Skyvern's AI recognizes multi-field TOTP inputs and handles them correctly.
</Note>
---
## Timeouts and polling
Skyvern waits for 2FA codes based on configurable timeouts:
| Setting | Default | Description |
|---------|---------|-------------|
| Polling interval | 10 seconds | How often Skyvern checks for new codes |
| Polling timeout | 15 minutes | Maximum wait time before failing |
If you're pushing codes, ensure your forwarding pipeline delivers codes within the timeout window.
---
## List recent codes
Debug your 2FA integration by listing recent codes received:
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=user@example.com&limit=10" \
-H "x-api-key: $SKYVERN_API_KEY"
```
**Query parameters:**
| Parameter | Description |
|-----------|-------------|
| `totp_identifier` | Filter by identifier (email, phone, etc.) |
| `workflow_run_id` | Filter by specific workflow run |
| `otp_type` | Filter by type: `totp` or `magic_link` |
| `limit` | Number of records (default 50, max 200) |
<Note>
Skyvern only returns codes from the last 10 minutes (configurable via `TOTP_LIFESPAN_MINUTES`).
</Note>
---
## Next steps
<CardGroup cols={2}>
<Card title="Store Credentials" icon="key" href="/developers/credentials/store-credentials">
Set up your credential vault integration
</Card>
<Card title="Troubleshooting" icon="wrench" href="/developers/credentials/troubleshooting-login">
Debug 2FA and login failures
</Card>
</CardGroup>
@@ -0,0 +1,495 @@
---
title: Store Credentials
subtitle: Securely manage login credentials, credit cards, and API secrets
description: Create, manage, and delete credentials using Skyvern's credential API. Store passwords, credit cards, and API secrets in Bitwarden, 1Password, Azure Key Vault, or a custom vault.
slug: developers/credentials/store-credentials
keywords:
- create_credential
- get_credentials
- delete_credential
- password
- credit card
- secret
- Bitwarden
- 1Password
- Azure Key Vault
- custom vault
---
Skyvern provides a credential management layer that gives you a unified API to create, use, and delete credentials. Your actual secrets are never stored in Skyvern. They live in your external vault (Bitwarden by default, or 1Password, Azure Key Vault, or your own service).
---
## How it works
When you create a credential via Skyvern's API, two things happen:
**Skyvern stores metadata** for easy lookup: credential names, IDs like `cred_xyz789`, usernames, and non-sensitive identifiers (like the last 4 digits of a card). This lets you list and manage credentials without exposing secrets.
**Your vault stores the secrets**: passwords, TOTP keys, full card numbers, and API tokens. Skyvern only retrieves these at runtime when needed, then discards them immediately after use.
```mermaid
flowchart LR
subgraph Your Infrastructure
Vault[(Your Vault<br/>Bitwarden, 1Password, Azure, etc.)]
end
subgraph Skyvern
Fetch[Fetch at runtime]
Fill[Fill forms]
end
subgraph Outputs
Browser[Browser]
Logs[Logs & LLM]
end
Vault -->|secrets| Fetch
Fetch -->|real values| Fill
Fill -->|real values| Browser
Fetch -.->|"placeholders<br/>(BW_PASSWORD)"| Logs
```
This gives you:
- **Friendly IDs**: Reference credentials by `cred_xyz789` instead of vault-specific item IDs
- **Vault abstraction**: Switch between Bitwarden, Azure, or custom vaults without changing your code
- **Security by design**: Secrets never appear in logs, API responses, or LLM prompts
---
## Credential types
Skyvern supports three credential types, each designed for specific use cases.
### Password credentials
Store usernames, passwords, and optional TOTP secrets for website logins.
<CodeGroup>
```python Python
import os
from skyvern import Skyvern
client = Skyvern(api_key=os.getenv("SKYVERN_API_KEY"))
credential = await client.create_credential(
name="Acme Portal Login",
credential_type="password",
credential={
"username": "user@example.com",
"password": "secure_password_here",
},
)
print(f"Credential ID: {credential.credential_id}")
```
```typescript TypeScript
import { SkyvernClient } from "@skyvern/client";
const client = new SkyvernClient({
apiKey: process.env.SKYVERN_API_KEY,
});
const credential = await client.createCredential({
name: "Acme Portal Login",
credential_type: "password",
credential: {
username: "user@example.com",
password: "secure_password_here",
},
});
console.log(`Credential ID: ${credential.credential_id}`);
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Portal Login",
"credential_type": "password",
"credential": {
"username": "user@example.com",
"password": "secure_password_here"
}
}'
```
</CodeGroup>
### Credit card credentials
Store payment information for checkout automations. Skyvern only stores the last 4 digits in metadata for identification.
<CodeGroup>
```python Python
credential = await client.create_credential(
name="Corporate Card",
credential_type="credit_card",
credential={
"card_number": "4242424242424242",
"card_cvv": "123",
"card_exp_month": "12",
"card_exp_year": "2028",
"card_brand": "visa",
"card_holder_name": "John Smith",
},
)
```
```typescript TypeScript
const credential = await client.createCredential({
name: "Corporate Card",
credential_type: "credit_card",
credential: {
card_number: "4242424242424242",
card_cvv: "123",
card_exp_month: "12",
card_exp_year: "2028",
card_brand: "visa",
card_holder_name: "John Smith",
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Corporate Card",
"credential_type": "credit_card",
"credential": {
"card_number": "4242424242424242",
"card_cvv": "123",
"card_exp_month": "12",
"card_exp_year": "2028",
"card_brand": "visa",
"card_holder_name": "John Smith"
}
}'
```
</CodeGroup>
**Supported card brands:** `visa`, `mastercard`, `amex`, `discover`
### Secret credentials
Store API keys, tokens, or other sensitive strings for use in HTTP Request blocks or custom integrations.
<CodeGroup>
```python Python
credential = await client.create_credential(
name="API Key",
credential_type="secret",
credential={
"secret_value": "sk-abc123xyz",
"secret_label": "Production API Key", # optional
},
)
```
```typescript TypeScript
const credential = await client.createCredential({
name: "API Key",
credential_type: "secret",
credential: {
secret_value: "sk-abc123xyz",
secret_label: "Production API Key",
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "API Key",
"credential_type": "secret",
"credential": {
"secret_value": "sk-abc123xyz",
"secret_label": "Production API Key"
}
}'
```
</CodeGroup>
---
## Vault integrations
Skyvern integrates with external password managers so credentials never leave your infrastructure.
### Bitwarden
Connect Skyvern to your Bitwarden organization to use existing vault items.
**Cloud setup:**
1. Create a Bitwarden organization at [bitwarden.com](https://bitwarden.com)
2. Create a collection to share with Skyvern
3. Contact [support@skyvern.com](mailto:support@skyvern.com) to complete the integration
4. Get your collection ID from the Bitwarden URL
5. Reference credentials by collection ID in your workflows
**Self-hosted setup:**
For self-hosted Bitwarden or Vaultwarden, configure these environment variables:
```bash
SKYVERN_AUTH_BITWARDEN_ORGANIZATION_ID=your-org-id
SKYVERN_AUTH_BITWARDEN_MASTER_PASSWORD=your-master-password
SKYVERN_AUTH_BITWARDEN_CLIENT_ID=user.your-client-id
SKYVERN_AUTH_BITWARDEN_CLIENT_SECRET=your-client-secret
BW_HOST=https://your-bitwarden-server.com
```
### 1Password
Connect via service account tokens for secure credential access.
1. Create a 1Password service account with access to your vault
2. Store the service account token in Skyvern:
```bash
curl -X POST "https://api.skyvern.com/v1/credentials/onepassword/create" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"token": "your-1password-service-account-token"
}'
```
3. Reference vault items by ID in your workflows
### Azure Key Vault
Store credentials in Azure Key Vault for enterprise environments.
```bash
curl -X POST "https://api.skyvern.com/v1/credentials/azure_credential/create" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"credential": {
"client_id": "your-azure-client-id",
"client_secret": "your-azure-client-secret",
"tenant_id": "your-azure-tenant-id"
}
}'
```
### Custom HTTP vault
Integrate your own credential service via HTTP API. Your service must implement these endpoints:
| Endpoint | Method | Description |
|----------|--------|-------------|
| `{base_url}` | POST | Create credential, return `{"id": "..."}` |
| `{base_url}/{id}` | GET | Return credential data |
| `{base_url}/{id}` | DELETE | Delete credential |
Configure via environment variables:
```bash
CREDENTIAL_VAULT_TYPE=custom
CUSTOM_CREDENTIAL_API_BASE_URL=https://credentials.company.com/api/v1/credentials
CUSTOM_CREDENTIAL_API_TOKEN=your_api_token
```
Or via API for per-organization configuration:
```bash
curl -X POST "https://api.skyvern.com/v1/credentials/custom_credential/create" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"config": {
"api_base_url": "https://credentials.company.com/api/v1/credentials",
"api_token": "your_api_token"
}
}'
```
---
## Using credentials in workflows
Workflows are the recommended way to use credentials. Add a credential parameter to your workflow, then reference it in login blocks.
<CodeGroup>
```python Python
# Run a workflow with credential parameter
result = await client.run_workflow(
workflow_id="wpid_abc123",
parameters={
"login_credential": "cred_xyz789", # Your credential ID
"target_url": "https://portal.example.com",
},
)
```
```typescript TypeScript
const result = await client.runWorkflow({
body: {
workflow_id: "wpid_abc123",
parameters: {
login_credential: "cred_xyz789",
target_url: "https://portal.example.com",
},
},
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/workflows" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "wpid_abc123",
"parameters": {
"login_credential": "cred_xyz789",
"target_url": "https://portal.example.com"
}
}'
```
</CodeGroup>
<Note>
You can also manage credentials directly from the Skyvern UI. See the [Managing Credentials](/cloud/managing-credentials/overview) guide for details.
</Note>
---
## Using credentials with login
For direct login automations, use the dedicated `login` method which handles credential retrieval and authentication:
<CodeGroup>
```python Python
result = await client.login(
credential_type="skyvern",
url="https://portal.example.com/login",
credential_id="cred_xyz789",
prompt="Navigate to the dashboard after logging in",
)
```
```typescript TypeScript
const result = await client.login({
credential_type: "skyvern",
url: "https://portal.example.com/login",
credential_id: "cred_xyz789",
prompt: "Navigate to the dashboard after logging in",
});
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/run/tasks/login" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"credential_type": "skyvern",
"url": "https://portal.example.com/login",
"credential_id": "cred_xyz789",
"prompt": "Navigate to the dashboard after logging in"
}'
```
</CodeGroup>
**Credential types for login:**
| Type | Description |
|------|-------------|
| `skyvern` | Use credentials created via Skyvern's API (stored in your configured vault) |
| `bitwarden` | Directly reference Bitwarden vault items by collection/item ID |
| `1password` | Directly reference 1Password vault items by vault/item ID |
| `azure_vault` | Directly reference Azure Key Vault secrets by name |
---
## Managing credentials
### List credentials
<CodeGroup>
```python Python
credentials = await client.get_credentials()
for cred in credentials:
print(f"{cred.name}: {cred.credential_id}")
```
```bash cURL
curl -X GET "https://api.skyvern.com/v1/credentials" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
### Get credential metadata
<CodeGroup>
```python Python
credential = await client.get_credential("cred_xyz789")
print(f"Name: {credential.name}")
print(f"Type: {credential.credential_type}")
```
```bash cURL
curl -X GET "https://api.skyvern.com/v1/credentials/cred_xyz789" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
<Note>
The GET endpoint returns metadata only, never the actual credential values. This is by design for security.
</Note>
### Delete a credential
<CodeGroup>
```python Python
await client.delete_credential("cred_xyz789")
```
```bash cURL
curl -X POST "https://api.skyvern.com/v1/credentials/cred_xyz789/delete" \
-H "x-api-key: $SKYVERN_API_KEY"
```
</CodeGroup>
<Warning>
Credential deletion is permanent. Workflows using the deleted credential will fail on their next run.
</Warning>
---
## Security architecture
Skyvern's credential handling is designed with security at every layer:
1. **Vault fetch**: Credentials are retrieved from your external vault only when needed
2. **Memory only**: Values exist in Skyvern's memory briefly during execution
3. **Placeholder tokens**: When sending data to LLMs, real values are replaced with tokens like `BW_PASSWORD`
4. **No persistence**: Real values are never written to databases, logs, or API responses
5. **LLM isolation**: Credentials are never sent to language models. The LLM sees only placeholder tokens
<Note>
When you view a run's artifacts or recordings, you'll see placeholder values like `BW_PASSWORD`, `BW_USERNAME`, or `BW_TOTP` instead of actual credentials.
</Note>
---
## Next steps
<CardGroup cols={2}>
<Card title="Handle 2FA" icon="shield" href="/developers/credentials/handle-2fa">
Set up two-factor authentication for your automations
</Card>
<Card title="Troubleshooting" icon="wrench" href="/developers/credentials/troubleshooting-login">
Debug common login failures
</Card>
</CardGroup>
@@ -0,0 +1,349 @@
---
title: Troubleshooting Login Failures
subtitle: Debug common authentication issues in your automations
description: Debug common login failures in Skyvern automations including credential errors, expired 2FA codes, CAPTCHA blocks, SSO redirects, and multi-step login flows. Includes a step-by-step debugging checklist.
slug: developers/credentials/troubleshooting-login
keywords:
- login failure
- debug
- expired code
- CAPTCHA block
- SSO redirect
- multi-step login
- session timeout
- checklist
- recording
- screenshot
---
Login failures are the most common issue in web automation. This guide covers the most frequent problems and how to resolve them.
---
## Common failure patterns
### Credentials not entered
**Symptoms:** Task completes but login never happened. The final screenshot shows the login page.
**Causes:**
- Credential parameter not linked to workflow
- Wrong `credential_id` referenced
- Vault connection failed
**Solutions:**
1. Verify the credential exists:
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/cred_xyz789" \
-H "x-api-key: $SKYVERN_API_KEY"
```
2. Check workflow parameter configuration to ensure the credential parameter is linked to a Login block
3. For vault integrations (Bitwarden, 1Password), verify connectivity:
- Check vault credentials are valid
- Ensure collection/vault IDs are correct
- Test vault access independently
---
### Wrong credentials entered
**Symptoms:** Site shows "Invalid username or password" error.
**Causes:**
- Credentials stored incorrectly in your vault
- Site expects different format (email vs username)
- Password contains special characters causing issues
**Solutions:**
1. **Verify credentials work manually**: Log in to the site yourself with the same credentials
2. **Check username format**: Some sites require email, others want a username:
```
❌ john.smith
✓ john.smith@company.com
```
3. **Test credential retrieval**: Create a simple test task to verify Skyvern can access the credential
4. **Check for copy/paste errors**: Re-enter credentials in your vault, avoiding trailing spaces
---
### 2FA code expired
**Symptoms:** "Invalid code" or "Code expired" error after entering TOTP.
**Causes:**
- Clock drift between Skyvern and your authenticator
- Code fetched too early in the 30-second window
- Multi-field entry took too long
**Solutions:**
1. **Skyvern handles timing automatically**: If a TOTP code has less than 20 seconds remaining, Skyvern uses the next code
2. **For pushed codes**: Ensure your forwarding pipeline sends codes promptly. Delays over 30 seconds cause expiration.
3. **Check system clocks**: If self-hosting, ensure your server time is synchronized (NTP)
4. **Retry the run**: Intermittent timing issues often resolve on retry
---
### 2FA code never received
**Symptoms:** Task times out waiting for verification code.
**Causes:**
- Push endpoint not forwarding codes
- `totp_url` returning errors
- `totp_identifier` mismatch between run and push
**Solutions:**
1. **Verify your push endpoint**: Check that it's receiving and forwarding codes:
```bash
# Test your Zapier/webhook endpoint manually
curl -X POST "https://api.skyvern.com/v1/credentials/totp" \
-H "x-api-key: $SKYVERN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"totp_identifier": "user@example.com",
"content": "Your code is 123456",
"source": "email"
}'
```
2. **Check `totp_identifier` matches**: The identifier in your login must exactly match what you push:
```python
# These must match exactly
result = await client.login(
credential_type="skyvern",
credential_id="cred_xyz789",
totp_identifier="user@example.com", # ← This
...
)
await client.send_totp_code(
totp_identifier="user@example.com", # ← Must match this
...
)
```
3. **List recent codes** to verify they're being received:
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=user@example.com" \
-H "x-api-key: $SKYVERN_API_KEY"
```
4. **For pull-based 2FA**: Check your endpoint returns the correct format:
```json
{
"task_id": "tsk_123456",
"verification_code": "123456"
}
```
---
## Site-specific issues
### CAPTCHA blocking login
**Symptoms:** Login page shows CAPTCHA challenge that blocks automation.
**Solutions:**
1. **Use residential proxies**: Many CAPTCHAs trigger on datacenter IPs:
```python
result = await client.run_task(
url="https://portal.example.com/login",
prompt="Log in to the portal",
proxy_location="RESIDENTIAL",
)
```
2. **Some CAPTCHAs can be solved**: Skyvern's AI can solve simple image-based challenges
3. **Browser profiles help**: Persistent browser state reduces CAPTCHA frequency:
```python
result = await client.login(
credential_type="skyvern",
url="https://portal.example.com/login",
credential_id="cred_xyz789",
browser_profile_id="bp_abc123",
)
```
4. **For persistent CAPTCHAs**: Contact [support@skyvern.com](mailto:support@skyvern.com) for enterprise CAPTCHA solutions
---
### SSO/OAuth redirects
**Symptoms:** Task fails when encountering "Sign in with Google/Microsoft" or similar SSO flows.
**Solutions:**
1. **Prefer direct credentials**: SSO flows involve multiple domains and are harder to automate. If possible, use direct username/password login.
2. **For required SSO**: Use browser sessions to maintain authentication state:
```python
# First run: Complete SSO manually or with Skyvern
result = await client.run_task(
url="https://portal.example.com/login",
prompt="Log in using Google SSO",
browser_session_id="bs_xyz789", # Persistent session
)
# Subsequent runs: Reuse the authenticated session
result = await client.run_task(
url="https://portal.example.com/dashboard",
prompt="Navigate to reports",
browser_session_id="bs_xyz789",
)
```
3. **Check for direct login options**: Many sites offer traditional login alongside SSO (often under "Other login options")
---
### Multi-step login flows
**Symptoms:** Task enters username but fails to proceed to password page, or misses subsequent steps.
**Solutions:**
1. **Increase `max_steps`**: Multi-step logins require more navigation:
```python
result = await client.run_task(
url="https://portal.example.com/login",
prompt="Log in with my credentials",
max_steps=15, # Default is 10
)
```
2. **Use explicit prompts**: Guide Skyvern through the steps:
```python
result = await client.run_task(
url="https://portal.example.com/login",
prompt="""
1. Enter the username and click Next
2. Wait for the password page to load
3. Enter the password and click Sign In
4. If 2FA is required, enter the code
""",
)
```
<Tip>
For login flows with credentials, use the `login()` method, which handles credential retrieval and 2FA automatically. Use `run_task()` only for general automation without credential management.
</Tip>
3. **Review recordings**: Watch the recording artifact to see exactly where the flow breaks
---
## Debugging checklist
Use this checklist to systematically debug login failures:
<Accordion title="Step-by-step debugging process">
**1. Check run status**
```bash
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID" \
-H "x-api-key: $SKYVERN_API_KEY"
```
Look at `status` and `failure_reason`.
**2. Review the recording**
Download the recording artifact and watch where the automation fails:
```bash
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID/artifacts?artifact_type=recording" \
-H "x-api-key: $SKYVERN_API_KEY"
```
**3. Check the final screenshot**
```bash
curl -X GET "https://api.skyvern.com/v1/runs/YOUR_RUN_ID/artifacts?artifact_type=screenshot_final" \
-H "x-api-key: $SKYVERN_API_KEY"
```
**4. Verify credential access**
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/YOUR_CREDENTIAL_ID" \
-H "x-api-key: $SKYVERN_API_KEY"
```
**5. For 2FA issues, check code history**
```bash
curl -X GET "https://api.skyvern.com/v1/credentials/totp?totp_identifier=YOUR_IDENTIFIER" \
-H "x-api-key: $SKYVERN_API_KEY"
```
**6. Review LLM reasoning**
Check `llm_request` and `llm_response` artifacts to understand what the AI was thinking.
</Accordion>
---
## Error messages reference
| Error | Meaning | Fix |
|-------|---------|-----|
| `FailedToGetTOTPVerificationCode` | HTTP request to `totp_url` failed | Check endpoint availability and response format |
| `NoTOTPVerificationCodeFound` | Polling timed out without receiving code | Ensure codes are pushed or endpoint returns codes |
| `TOTPExpiredError` | Code became invalid during entry | Usually auto-resolved on retry; check timing pipeline |
| `CredentialParameterNotFoundError` | Referenced credential parameter not found | Verify credential ID and parameter configuration |
| `CredentialParameterParsingError` | Failed to parse credential data | Check credential format matches expected schema |
| `CustomCredentialConfigurationError` | Custom vault service misconfigured | Verify API base URL and token are set correctly |
---
## Getting help
If you're stuck after trying the above solutions, contact Skyvern support with:
1. **Run ID**: The `run_id` from your failed run
2. **Recording**: Download and attach the recording artifact
3. **Description**: What you expected vs. what happened
4. **Target site**: The URL you're trying to automate (if not confidential)
Contact [support@skyvern.com](mailto:support@skyvern.com) or join our [Discord](https://discord.gg/skyvern) for community help.
---
## Next steps
<CardGroup cols={2}>
<Card title="Store Credentials" icon="key" href="/developers/credentials/store-credentials">
Review credential setup
</Card>
<Card title="Handle 2FA" icon="shield" href="/developers/credentials/handle-2fa">
Configure two-factor authentication
</Card>
</CardGroup>