同步完整源码 - 2026-05-24
This commit is contained in:
@@ -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>
|
||||
Reference in New Issue
Block a user